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Preface 





The APC III] MS-DOS Programmer's Reference Guide Sup- 
plement provides information that is specific to MS-DOS on 
the APC III computer. Information contained in this docu- 
ment is intended primarily for programmers writing software 
for the APC III] using the MS-DOS operating system. The 
following documents contain additional information on the 
APC III and the MS-DOS operating system. 

MS-DOS User's Guide 

APC III Supplement to MS-DOS User’s Guide 

A PC III Owner’s Guide 

Macro Assembler Manual 

APC III System Reference Guide* 

GS X-86 User’s Guide 

GW-BASIC User’s Guide 


NEC APC III ROM BIOS listing 


(available on diskette)* 
NEC wePD7220-GDC Reference Guide 


* Available separately 


Chapter 1 
MS-DOS System Files 





Overview 


The heart of the MS-DOS Operating System consists of three 
programs: IO.SYS, MSDOS.SYS, and COMMAND.COM. 
The first two programs are considered resident; once loaded, 
they remain in memory until the MS-DOS session 1s over. The 
IO.SYS program is the customized part of MS-DOS; it was 
written by NEC for the APC III. The MSDOS.SYS program 
provides the basic operating system services. These two pro- 
grams are stored on the System diskette in hidden files. The file 
names do not appear in the diskette directory. The COM- 
MAND.COM program is the command processor. It serves as 
an intermediary between MSDOS.SYS and other programs, 
for example, applications, utilities, and external MS-DOS 
commands. 


The following three sections describe the IO.SYS, MSDOS. 
SYS,and COMMAND.COM programs in greater detail. The 
last section explains the ANSI.SYS program, which provides a 
set of ANSI-compatible escape sequences for cursor control, 
screen deletion, display attribute control, and keyboard map- 
ping. Appendix A, MS-DOS Memory Maps, gives additional 
information on memory maps, independent common memory, 
and CMOS battery-backup memory. 





MS-DOS System Files 
The I/O (Input/Output) System (IO.SYS) 


IO.SYS adapts the APC III] hardware-dependent and firm- 
ware (ROM BIOS) routines for use with the MS-DOS Operat- 
ing System. 


Device Drivers 


The I/O system consists of a set of device driver routines. Each 
device driver provides access to a particular part of the APC 
III hardware set. The device drivers can be broken down into 
those which service “character” devices and those which ser- 
vice “block” devices. IO.SYS presents the DOS (Disk Operat- 
ing System) with a standard software interface which the DOS 
can use to request character and block device I/O. This stan- 
dard interface permits many different hardware sets to use a 
DOS program. 


Character device I/O includes the keyboard, console, printer, 
and RS-232 serial port. These devices present the I/O system 
with a serial stream of ASCII characters. Typical I/O-system 
services for character devices include reporting the status of 
the device, and transferring characters to or from the device as 
requested by the DOS. 


Block device I/O is generally the disk drives, or devices that 
present the I/O system with a random-access, block-oriented 
structure. The I/O must provide the DOS with a summary of 
the device structure, for example, sector size, number of sec- 
tors, and allocation unit size. It must also provide the capabil- 
ity to read and write to specific sectors (blocks), since the I/O 
system does not recognize information as directories or files. 


MS-DOS permits another way to incorporate additional 
device drivers into the I/O system memory other than through 
the IO.SYS file. These drivers are referred to as “installable” 
device drivers. When MS-DOS is first loaded, a process called 
SYSINIT examines the default drive’s root directory for the 
file CONFIG.SYS. The CONFIG.SYS file can contain records 
specifying additional device drivers to be ioaded into memory 
from disk files before MS-DOS begins to run. 
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NEC provides an installable driver that is stored inthe ANSL.- 
SYS file. If this driver is loaded at boot time, it becomes the 
new driver for the console output (CON). When MS-DOS 
requests output on CON, the new driver from ANSI.SYS 
replaces the default driver in the JO.SYS file. The ANSI.SYS 
driver has a special feature. It can implement the ANSI- 
compatible escape sequences. These character sequences, 
when sent to the CON device, have special meanings to the 
device driver. The ANSI.SYS driver will be installed automat- 
ically when you load MS-DOS from the system diskette. If you 
do not wish to have ANSI.SYS loaded, you must modify 
CONFIG.SYS by removing the DEVICE=ANSI.SYS com- 
mand. Refer to Appendix B in this supplement for further 
information. 


ROM BIOS 


The APC III contains a lower level of software used by the I/O 
system, called ROM (read-only memory) BIOS (Basic Input / 
Output System). The ROM BIOS is stored in nonerasable 
memory chips in the APC III system unit, instead of on 
diskette. It provides the most primitive level of I/O support for 
the APC III hardware set. By using ROM BIOS, the IO.SYS 
file can be kept smaller. 


For programmers, there is a major difference between the I/O 
system and the ROM BIOS. The interface between the DOS 
and I/O system is hidden to the programmer and therefore 
cannot be used directly by user programs. The interface 
between the I/O system and ROM BIOS can be used directly 
by user programs and can bypass the DOS/IO system. There- 
fore, access to the hardware is accomplished faster and more 
directly. Also, certain functions not available through the 
DOS calls may be accessible via the ROM BIOS calls. Using 
ROM BIOS will make the software machine dependent on the 
APC III. For more information, refer to the section “ROM 
BIOS Interface.” 
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MS-DOS System Files 
The DOS System (MSDOS.SYS) 


The services provided by the I/O system are used by the DOS, 
which in turn provides basic operating system services, such as 
program loading, the file and character I/O to COM MAND.- 
COM and user applications. 


The DOS arranges the block devices into logical volumes 
(diskettes), which are divided into directories, subdirectories, 
and files. The DOS also provides device-independent file I/O; 
that is, the ability to open a device as a file, read from it, and 
write to it, as if it were a file on a block device. 


The command processor, user programs, applications, utili- 
ties, and external MS-DOS commands make calls tothe DOS 
for services. The calls are made using the 8086 software inter- 
rupt instruction with interrupt types 20H-26H, where H indi- 
cates hexadecimal. The MS-DOS Programmer’s Reference 
Guide contains a detailed description of the available DOS 
calls. Programmers using languages other than assembler may 
not need to use these calls explicitly. This is because most 
language packages that run under MS-DOS translate lan- 
guage I/O statements into DOS calls, transparently to the 
user. All calls described may be accessed from any high-level 
language that supports an interface to assembly language sub- 
routines. Refer to Appendix C of this supplement for more 
information. 


The Command Processor (COMMAND.COM) 


The command processor is stored on diskette in a file called 
COMMAND.COM. It is loaded during system boot and 
comprises three portions: 

@ resident 

® initialization 


@ transient. 
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Resident 


The resident portion is the part of the command processor that 
cannot be overwritten. It is loaded into memory immediately 
following the end of the DOS code in low memory, and 
remains in memory at all times. All standard MS-DOS error 
handling is done within the resident portion. This includes 
displaying error messages and interpreting replies to messages 
with “Abort, Retry, or Ignore?” prompts. The resident con- 
tains routines to process interrupt types 22H (terminate 
address), 23H (control C exit address), and 24H (fatal error 
abort address). It also contains the routine needed to reload 
the transient portion of the command processor. 


Initialization 


The initialization portion contains code which is executed only 
once at system startup. It contains the routines necessary to 
initiate execution of the AUTOEXEC.BAT file (if present). 
The initialization portion of the command processor is over- 
written by the first program that the command processor 
loads. 


Transient 


The transient portion contains routines that execute the inter- 
nal MS-DOS commands, the batch file processor, and the 
routines that display the “A>” prompt and receive user key- 
board commands. The transient portion resides in the high end 
of memory. It may be overwritten if an application or utility 
needs the memory that it occupies. 


Once the transient portion is overwritten, the resident portion 
will detect it (using checksum), and attempt to reload it from 
the COMMAND.COM file using the current default drive. If 
the volume mounted tn the default drive does not contain the 
COMMAND.COM file, the user will be instructed to insert a 
diskette with the file. If the default drive is a nonremovable 
media type, the system will hang. It will be waiting for the user 
to insert a new diskette in a fixed media drive. To avoid this, it 
is recommended that COMMAND.COM be copied to the 
root directory of each nonremovable volume. Alternatively, 
the SET command may be used to specify COMSPEC, the 
pathname used in locating COMMAND.COM. Refer to the 
MS-DOS User’s Guide for a description of the SET command. 
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ANSI-Compatible Console Driver (ANSI.SYS) 


The ANSI.SYS driver provides a set of ANSI-compatible 
escape sequences which may be used for cursor control, screen 
deletion operations, display attribute control, and keyboard 
remapping. 


Before you can access the ANSI.SYS driver, it must be 
installed. To do this, the files CONFIG.SYS and ANSI.SYS 
must be present on the boot volume. The CONFIG.SYS file 
must contain a line reading “DEVICE=ANSI.SYS”. This line 
will direct the SYSINIT module to load the driver from the 
ANSLSYS file. These files are provided on the MS-DOS 
system diskette. 


Once the driver is installed as the CON device output driver, 
any of the ANSI sequences may be sent by calling the character 
I/O functions of MS-DOS. Characters written to a file named 
CON, using the file oriented DOS calls, will also be processed 
by the ANSI driver. 


Programs that are written in languages other than assembler 
may already use these functions via I/O support in the lan- 
guage. For example, in MS-BASIC the “escape [2J” function 
could be sent to the driver with the following statement: 


PRINT CHR&(27); “[2J” 


When executed, the interpreter translates the BASIC PRINT 
statement into the appropriate calls to the DOS functions 
needed to display the string. Since the string is a valid ANSI 
escape sequence (Clear Entire Screen), the driver will clear the 
screen. 


A key remapping function is provided in ANSI.SYS. This 
escape sequence allows you to change the codes produced by 
any key (and SHIFT state). Therefore, when keys are pressed, 
it appears to MS-DOS as if the character(s) programmed for 
that key have been pressed, instead of the actual characters 
displayed on the keys. 
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The maximum length of a string remapped “into” a key that 
does not use an extended ASCII code is 253 characters. For 
keys that use an extended ASCII code, the length is 252 
characters. There is an overall limit on the number of keys that 
can be reprogrammed and the total length of the string that the 
keys are programmed to produce. The limiting factor is the size 
of the table in the driver that holds the remapping information. 
The table is 512 bytes long. When the table becomes full, all 
further requests for remapping are ignored. If a remapping 
request is made that would require more bytes in the table than 
are available, the request for further redefinition is ignored. 


The amount of table space occupied by a remapping request 
for expansion to N characters is 


Length = 2+ N bytes (for requests to remap keys with 
standard ASCII codes). 


Length = 3 + N bytes (for request to remap keys with 
extended ASCII codes). 


The definitions used by the MS-DOS command-line template- 
editing feature are present by default, and use approximately 
60 of the total bytes in the table. 


The KEY utility may be used to determine what remappings 
are currently in effect, and how much space remains for further 
definitions. See the A PC JI] MS-DOS User’s Guide Supple- 
ment for information onthe KEY utility. Referto Appendix B 
foracomplete list of the escape sequences implemented by the 
ANSI.SYS device driver. 
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Optional Dual RS-232C Serial Port Device Driver 
(OPTRS232.SYS) 


The OPTRS232.SYS installable device driver provides sup- 
port for two additional RS-232C serial ports; these two ports 
are referred to as AUX2 and AUX3. When the driver is 
installed during system initialization, these two serial ports can 
be used in the same manner as the standard serial port, AUX. 
To install the driver, the CONFIG.SYS file must containa line 
reading “DEVICE = OPTRS232.SYS”. The CONFIG.SYS 
and OPT RS232.SYS files must be located in the root directory 
of the system boot drive along with the system files. Remember 
to copy these files along with the system files when changing or 
creating a new boot drive. 


OPTRS232.SYS also provides a set of routines which function 
exactly like the ROM BIOS calls to RS232C_IO. These func- 
tion calls, which are described in Appendix E, can be accessed 
through interrupt IEH, OPTRS232C_IO. 


The two ports on the APC-H156 option board can be config- 
ured with the same parameters that are available for the stand- 
ard port. The SETCOM utility may be used to configure all of 
the serial ports. See the section on Custom Utilities inthe A PC 
III Supplement to the MS- DOS User’s Guide for additional 
information. 


Chapter 2 
MS-DOS Initialization 





Initialization Procedures 


The bootstrap loading process is initiated in the following 
three circumstances: 


@ when the system is powered on 


@ the RESET button is pressed after the system is 
powered on 


@ the <Ctrl>, <Fnc>, and <Break Stop> keys are 
pressed simultaneously after the system 1s powered on. 


When the bootstrap-loading process is initiated, control is 
passed (by hardware) to the initialization code in ROM BIOS. 
The initialization code then executes several self-diagnostic 
routines that initialize and check certain aspects of the system 
hardware such as the 8259 interrupt controller and 7220 GDC 
(Graphics Display Controller). The system also performs a 
quick memory test, if the system was just powered on, or the 
RESET button was pressed. 


Next, the ROM loader routine searches the block devices fora 
diskette or hard disk that holds the bootstrap loader in its 
reserved sector(s). When the unit is found, the bootstrap 
loader is read into memory from the diskette or disk and 
control is transferred to the bootstrap loader. 





MS-DOS Initialization 


The function of the bootstrap loader is to read the files IO.SYS 
and MSDOS.SYS into memory from their locations at the 
start of the data area of the disk or diskette. Control is then 
passed to an initialization routine in the IO.SYS code. The 
IO.SYS initialization routine initializes the IO system drivers 
and then passes control to SYSINIT, which is linked into the 
1O.SYS file. 


SYSINIT searches the diskette or disk for the CONFIG.SYS 
file. Once CONFIG.SYS is found, SYSINIT reads the file and 
processes the commands. Refer to Appendix D for details on 
the CONFIG.SYS commands. If CONFIG.SYS contains 
“DEVICE =” commands, then the specified installable drivers 
are loaded into memory (as an extension to the I/O system) 
from the indicated files. 


Finally, SYSINIT reinitializes the DOS code. Control is then 
passed via an EXEC call to the command processor. When 
COMMAND.COM initializes, it searches for a file named 
AUTOEXEC.BAT on the disk unit that the system was loaded 
with. If this file is found, the prompt for time and date is 
skipped, and the commands in AUTOEXEC.BAT are exe- 
cuted. By creating an AUTOEXEC.BAT file, you can custom- 
ize the startup procedures for an APC III. Refer to the MS- 
DOS User’s Guide for information on using .BAT (Batch) 
command files. 
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Chapter 3 


The APC III Video Display 
Memory (VRAM) 


Overview 


This section provides the experienced programmer with 
enough information to directly access the VRAM memory 
area In conjunction with the ROM BIOS CRT IO function 
calls. Itis nota comprehensive description of the APC III CRT 
display hardware and will not explain the operation of the 
NEC 7220 GDC chips. Instead, refer to the APC JI] System 
Reference Guide and the NEC uwPD7220-GDC Reference 
Guide. Appendix E gives detailed information on the ROM 
BIOS Call Functions. 


VRAM 


The APC III CRT display is memory mapped. The memory 
used to hold the data that is displayed (either ASCII characters 
or graphics) is directly accessible to the 8086 MPU (main 
processing unit) as an area of memory. This area 1s called video 
display memory, or VRAM. VRAM allows exceptionally fast 
character or graphics display operations, by simply moving 
data into and out of the VRAM area. Both graphics and text 
modes of operation are available. 
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Effects of VRAM on Applications 


The MS-DOS I/O system and ROM BIOS contain routines 
which may be used to send data to the display. Some applica- 
tions may benefit from the increased performance available by 
bypassing the DOS and ROM BIOS calls and writing directly 
to the VRAM. This will also require a little extra work from 
the programmer because the program will need to keep track 
of cursor position, scrolling, and the conversions between 
screen positions and memory addresses within the VRAM. 


GDCs 


Two NEC 7220 GDCs are at the heart of the CRT display 
controller hardware. They share access to the display memory 
areas with the 8086 MPU. The 7220s transform the contents of 
the VRAM areas into composite video signals required to 
drive monochrome or color monitors, or RF (Radio Fre- 
quency) converter/TV adapters for TV displays. 


The first GDC, referred to as the “master,” controls the stan- 
dard APC III text display modes. The second, or “slave,” GDC 
provides standard APC III graphics modes. Each GDC con- 
trols its own VRAM memory area. 


MASTER GDC 


The standard APC III comes with 8 K bytes of text VRAM for 
the master GDC. The area occupies 16 K bytes of MPU 
address space; however, only the lower 8 bits (even byte 
addresses) of each word are actually memory locations. This 
VRAM area provides enough memory for two text display 
pages, using eight different colors for each character. Several 
other character attributes, such as reverse video and underlin- 
ing, are also available. 


SLAVE GDC 


The standard APC III is equipped with 64 KB of VRAM for 
the slave GDC. This provides enough memory for two pages of 
a single graphics plane of up to 640 « 400 pixels. A color 
graphics expansion option may be added to provide an addi- 
tional 128 KB, and permitting the use of three color planes of 
up to 640 = 400 pixels each. 
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Display Modes 


Any of the modes listed in Table 3-1 may be selected using the 
ROM BIOS CRT I/O function calls. 


Table 3-1 ROM BIOS Display Modes 


Text 40 x 25 characters - monochrome | Master GDC 
Text 40 x 25 characters - color Master GDC 
Text 80 x 25 characters - monochrome | Master GDC 
Text 80 x 25 characters - color Master GDC 
Graphics 320 x 200 - monochrome Slave GDC 
Graphics 320 x 200 - color Slave GDC 
Graphics 640 = 200 - monochrome Slave GDC 
Graphics 640 x 200 - color Slave GDC 
Graphics 640 x 400 - monochrome Slave GDC 
Graphics 640 x 400 - color Slave GDC 


2 
Z 
Z 
Z 
2 
2 
Z 
Z 
Z 
2 





Note All color graphic modes require the presence of the 
Color Graphics option. All other modes are sup- 
ported on the standard unit. 


Any of these modes may be selected using the ROM BIOS 
CRT I/O function calls (Set A Display Mode). The active 
display page can also be set with a ROM BIOS call (Select 
Active Display Page). The hardware allows page selection 
through a bank-switching arrangement. Independent control 
of the active page to be displayed on the screen and the active 
page to be accessible by the MPU (in the address space) is 
provided by special hardware registers. The ROM BIOS calls 
always switch both of these features together. For information 
on direct access of the graphics page select hardware, refer to 
the APC III System Reference Guide. 
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TEXT AND GRAPHIC MODES 


The text modes controlled by the master GDC use a ROM 
character generator to produce the character set font. Refer to 
Appendix F fora listing of the displayable characters. In these 
modes each byte inthe VRAM contains the ASCII code of the 
character to be displayed. Each character has a corresponding 
byte in the attribute memory area. The ROM character gener- 
ator is used during the display of a character to convert the 
ASCII codes into the correct pixels of each scan line that 
makes up the character. The 40 x 25 character mode must be 
used for TV displays. CRT monitor type displays can use 
either 40 = 25 or 80 = 25 character modes. 


The ROM BIOS function calls provide many useful services 
when using these modes, such as cursor positioning, cursor 
type selection, selection of active page, window scrolling, and 
character and attribute display. 


The graphic modes controlled by the slave GDC use the graph- 
ics VRAM asa bit-mapped graphics area. In these modes, each 
bit in the VRAM corresponds to one pixel on the display. 


To produce characters on the screen in the 320 x 200 or 640 x 
200 modes, several bytes of data must be stored in the VRAM 
to activate the necessary bits to form a displayed character. 
The ROM BIOS CRT write character I/O functions converts 
the ASCII code into the proper pixel datain VRAM to display 
the character on the screen. For programs that do not use 
ROM BIOS, the operation can also be simplified using the 
capabilities of the 7220 GDC; however the details are not 
discussed here. A more complex user program could bypass 
this ROM BIOS feature, and write the necessary data directly 
to the VRAM. Alternate character fonts can be implemented 
in this manner. 


The APC III hardware is capable of operating both the master 
and slave 7220 GDCs concurrently. This hardware feature 1s 
not. however, supported by MS-DOS or the ROM BIOS calls. 
When using the ROM BIOS, only a single text or graphics 
mode is in effect at any time. 
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In all graphics modes, ROM BIOS offers routines which con- 
trol individual pixels, thereby freeing the user program for 
necessary address calculations in converting a logical (x,y) 
coordinate into a physical VRAM address. Additionally, 
ROM BIOS calls providing simple graphics figure drawing, 
including lines, circles, and rectangles, are supplied. 


ROM BIOS also provides functions to manipulate the palette 
registers. This feature allows arbitrary mapping of color plane 
bit combinations for a single pixel into arbitrary combination 
of output colors. Access to the registers is provided by the 
ROM BIOS. In all graphics display modes supported by the 
ROM BIOS, there is also a mapping switch in hardware (soft- 
ware programmable), allowing the GDC and MPU to bank- 
switch between two pages of graphics. This operation is sup- 
ported by the Select Active Display Page function within the 
CRT_IO ROM BIOS. 


The method used to access the VRAM memory will vary from 
language to language. In assembler, locations within the 
VRAM can be addressed using the usual segment:offset 
addressing scheme. From BASIC, a DEFSEG with PEEKs 
and POKE can be used. In some instances, there may be no 
way to access the VRAM directly. Instead, simple assembly 
language subroutines, called from the high-level language, can 
be written to access arbitrary memory locations. 


TEXT MODE VRAM MAPPING 


The text mode VRAM mapping provides separate areas for 
character codes and display attributes. The attribute area may 
be thought of as overlaying the text area. For example, to 
cause a reverse video “A” character to be displayed in the first 
character position, the program would place the ASCII code 
(41H) in the first character position of the VRAM, and the 
attribute control byte for reverse-video (04H) in the first char- 
acter position of the attribute area. 


In 80 x 25 text modes, the character codes are stored with the 
upper left character of the display mapped from the lowest 
address in the VRAM display page. All subsequent even 8086 
addresses contain the characters for the first line. After the 
80th character, the next even address is mapped to the first 
character of the second line of the display, and so forth. 
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The same arrangement is used in mapping the character 
attribute areas, so that the attribute byte for a given VRAM 
location is always 2000H bytes beyond the given address. The 
same arrangement is also true for 40 x 25 character text modes; 
however, only every other location from the 80 x 25 VRAM 
map is used. 


The attribute byte corresponding to each character in text 
VRAM allows the character to be modified in order to display 
any combinations of several variations of the character. The 
following attributes are available. 


Red color component (for color displays) or intensity 
Blue color component control (monochrome displays) 
Vertical strike-through 

Underline 

Reverse Video 

Blinking 

Overline 


Green color component : these combine into eight colors 


In the graphics modes, displays are built of combinations of 
individual pixels. Various colors are achieved by use of the 
palette registers and by combining colors through manipulat- 
ing the three pixels (in the three color planes) which control the 
color components (red, green, and blue). Refer to Appendix G 
for information on the VRAM CRT displays. 


S3-6 


Chapter 4 


The APC III Keyboard 
Device Drivers 






APC IIT Keyboard 


The APC III keyboard contains a total of 101 keys. Each key ts 
classified as a shift key or character key. The following are shift 
keys. 


<Fne> 

—C Ar 
<Caps Lock> 
<Shift> (2) 
<Grph |> 
<Grph 2> 
<Alt> 


The remainder of the keys are character keys. Each key (shift 
and character) has an assigned scan code which identifies it 
uniquely. The one exception is the two <Shift> keys, which 
share a scan code of 45. 


Each time a key 1s pressed or released, an internal 8048 micro- 
processor, housed in the keyboard unit, sends an 8-bit code in 
serial form to the APC III system unit. This code contains a 
7-bit scan code, which identifies the key, and 1-bit that indi- 
cates whether key contact has been made (switch closed) or 
broken (switch open). 
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When one of these characters is received, an interrupt occurs to 
the 8086 MPU. The interrupt activates a routine in ROM 
BIOS which receives and decodes the character. Since both 
shift and character key keystrokes are received in this manner, 
ROM BIOS must keep track of the current shift state as shift 
keystrokes occur. As character codes are received, ROM BIOS 
attempts to decode the ASCII code. Since there are more 
shift-state/character key combinations than a single 8-bit code 
can encode, not all are mapped directly into ASCII codes. 


Certain shift-state/key code combinations are disregarded 
entirely by ROM BIOS. Others are mapped into an “extended 
ASCII” code. The extended ASCII codes provide an addi- 
tional 256 codes which are used to represent selected character 
key/shift states. The extended ASCII codes can be thought of 
as an ASCII 0ON (NUL) character, followed by the extended 
ASCII code. This forces the ASCII NUL code itself to be 
mapped as an extended code. 


In most cases, combinations of shift states are undefined. For 
example, there is no such character as <Shift>, <Ctrl>, and 
<PF1>, as faras ROM BIOS is concerned. Only a single shift 
state applies to any single keystroke if the user is actually 
typing in more than a single shift state. For example, if both 
<Grph 1> and <Grph 2> are locked down, then ROM BIOS 
uses the following precedence list to determine which shift 
State is in effect. 


Highest — <Grph I>, <Grph 2>, <Alt>, <Ctrl>, <Shift>, <Fnce> «— Lowest 


There are exceptions to the “only one shift state” rule. <Grph 
1>and <Grph 2> can be used along with <Shift>to produce 
valid and unique extended ASCII codes. Refer to Appendix H 
for a complete summary of effective shift states. 


Once a keystroke has been classified, it is entered into a FIFO 
(First In First Out) queue as a 16-bit entry. If the character was 
mapped into a standard ASCII code, then the FIFO entry 
consists of the key’s scan code (8-bits), plus the ASCII code 
itself (8-bits). If the keystroke was mapped into extended 
ASCII, then the extended ASCII code (8-bits) plus the value 
OOH (8-bits) is entered in the FIFO. 


Certain character key/shift states do not map into either an 
ASCII or extended ASCII code. These keystrokes will be 
discarded (no FIFO entry will be made), and no further pro- 
cessing for the keystrokes will occur. 
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In the MS-DOS I/O, requests to read the keyboard result in 
calls to ROM BIOS. The calls determine whether characters 
are present in the FIFO (for status calls from the DOS), or 
when to get the next character in the FIFO (for character read 
calls from the DOS). Within the I/O keyboard driver routines, 
a final level of keyboard processing occurs. Before returning 
characters received from ROM BIOS tothe DOS, the console 
input driver (ANSI.SYS only) checks the character against a 
remapping list. If the character (standard or extended ASCII) 
has a corresponding entry in the remapping list, then the entry 
in the list is used to determine which characters the driver will 
return as the DOS requests them. This arrangement allows the 
driver complete flexibility in that every key on the keyboard 
can be remapped. 


It should be noted that the driver handles extended codes 
returned by the ROM BIOS only if the extended code has an 
entry in the key remapping list. Extended ASCII codes 
received from ROM BIOS which do not have a corresponding 
entry in the remapping list will be discarded by the I/O, and 
not returned to the DOS. Therefore, if it is desirable to have an 
extended ASCII keystroke/shift combination produce a code 
(or codes) via the DOS INT 21H character function calls, the 
mapping from extended ASCII to ASCII must be requested 
with the Keyboard Remapping escape sequence, or the KEY 
utility. 


After system initialization, only the unshifted PF keys (which 
use extended ASCII) used for the MS-DOS command line 
template editing functions are defined in the remapping list. 
All other PF keys (and shift states) will not return codes untila 
mapping has been specified. 
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Keystroke/Shift States Exceptions 


Certain keystroke/shift states have special predefined mean- 
ings, and fall outside of the rules mentioned in the previous 
discussion. They are recognized immediately by the interrupt 
handler for the keyboard in ROM BIOS. The following four 
keystroke/shift states are the exceptions. 


@ Break function 

@ Keyboard system reboot function 
@ Print screen image request 

@ Alt entry of decimal ASCII code 


The following sections explain each of the four keystroke/ shift 
states. 


Break Function 


The combination of the <Ctrl> shift key and the <Break 
Stop> character key will result in the keyboard routine signal- 
ing 8086 interrupt level 6H with a software interrupt. Also, the 
extended ASCII code 00H OOH will be returned via ROM 
BIOS. MS-DOS will not recognize these codes unless they 
have been remapped. By default, the Break interrupt vector is 
set to a null routine, which simply performs an IRET instruc- 
tion. It is up to the user to change the interrupt vector if a 
user-supplied Break routine is to be implemented. 


Keyboard System Reboot Function 


The combination of the <Fnc> and <Ctrl> shift keys, along 
with the <Break Stop> character key, will cause the APC III 
to perform a “warm start.” This feature may be useful in 
regaining control of the system if a user program is trapped in 
an infinite loop. 
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Print Screen Image Request 


The combination of the <Shift> key and <Print> character 
key will cause the text appearing on the CRT display to be 
printed to the default system printer. The combination of the 
<Shift> and <Ctrl> shift keys along with the <Print> char- 
acter key requests that the CRTDUMP resident extension 
program print acopy of the graphics image currently displayed 
on the screen. 


Neither of these combinations result in any codes being 
returned for ROM BIOS read keyboard calls. 


Alt Entry of Decimal ASCII Code 


A special feature of the APC III keyboard allows any ASCII 
code to be entered directly by typing its ASCII code in decimal. 
Press the <AIt> key and then type the three-digit decimal 
value of the desired character on the numeric keypad digit 
keys. Release the <AIt> key. If more than three characters are 
typed, a modulo 256 result is created. These three keys are 
interpreted as a character code. For example, to enter an 
ASCII DEL(ete) character (code 127, decimal), press the 
<AIlt> key and then type |, 2, and 7 digit keys on the numeric 
keypad. Release the <Alt> key. This entire sequence is equiv- 
alent to typing the <Del> key once. 
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ROM BIOS 


ROM BIOS provides device-level control of major {/O devices 
in the system unit. An assembly language programmer will 
have the ability to perform block or character-level I/O opera- 
tions using ROM BIOS routines. The I/O operations can be 
performed without concern for operating characteristics and 
device address. System services such as time of day are also 
provided. 


The goal is to provide an operational interface to the system 
and relieve the programmer from concern over hardware 
device characteristics. The BIOS interface insulates the user 
from the hardware allowing new devices to be added to the 
system, while retaining the BIOS-level interface to the device. 
In this manner, hardware modifications and enhancements 
become transparent to user programs. 


Use of BIOS 


Access to the BIOS functions is through the 8086 software 
interrupts. Each BIOS entry point is available through its own 
interrupt, which can be found in the Interrupt Vector listing in 
Appendix C. It is important to note that calls to the APC II] 
ROM BIOS are not portable to MS-DOS systems running on 
computers other than the APC III. 


Parameter Passing 


All parameters passed to and from the BIOS routines go 
through the 8086 registers. Refer to Appendix E for a sum- 
mary of the available ROM BIOS calls. For a more detailed 
discussion of the ROM BIOS, refer to the APC JI] System 
Reference Guide and the ROM BIOS lists, which reside on a 
diskette that must be ordered separately. 
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MS-DOS Memory Maps 







Figure A-] illustrates an overview of the MS-DOS Memory 


Map. 


0000:0000 
0040:0000 


0060:0000 


2000:0000 


4000:0000 
6000:0000 
8000:0000 
A000:0000 
A3FE:0000 
A800:0000 


BOOO0:0000 


CO00:0000 


FOOO0:0000 






ROM BIOS Working Storage Area (Refer 
to the ROM BIOS listings for details) 
10.SYS Version-| ndependent 

Common Memory 

Installable-Device Drivers (ANSI SYS) 


Command Processor (resident part of 
COMMAND.COM) 


User Memory 









OPTIONAL EXPANSION MEMORY 
(512 KB=128 KBx 4) 











Standard Video RAM for text 
(4 K in 8 K address space) 






CMOS (8 bytes) reserved for system use 









Standard Video RAM for graphics 
(2 x 32 KB bank switched) 


Optional Video RAM (Color Graphics) 
(2 x 2 x 32 KB bank switched) 


Boot Loader and ROM BIOS 







For a more detailed 
map, see Appendix C 
0:05FO-O5FF Reserved 
for Inter-Application 
Communications Area 


Up to a total of 
four 128 K memory 
expansion options 
may be added to 
bring the system 
memory up to a 
maximum of 640 K 
bytes of user RAM. 


Figure A-l MS-DOS Memory Map 
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MS-DOS System Version — Independent Common 
Memory Area 


The System Common Memcry area provides access to certain 
important MS-DOS I/O system items in a version-independent 
way. The following definitions in Table A-1 apply to all future 
versions of the MS-DOS I/O for the APC III. Future versions 
may include additional items not included in this appendix. 


Table A-1 System Common Memory (I/O Version 


Independent) 
Length 
Address in Bytes Contents 








0060:0000 I/O system initialization en- 


try point. 

I/O system version; ASCII 
dioit, 1,2, été. 

Reserved 


Copy of CMOS contents (see 
the following section). 


DWORD pointer to CON 
device control table. 


DWORD pointer to AUX 
device control tables. 


DWORD pointer to PRN 
device control table. 


DWORD pointer to CLK 
device control table. 


DWORD pointer to DSK 
device control table. 










0060:0003 










0060:0004 
0060:0008 










0060:0010 










0060:0014 









0060:0018 










0060:001C 










0060:0020 









0060:0024 
0060:002C 


Reserved 


DWORD pointer to config- 
uration table. 
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Table A-i System Common Memory (I/O Version 
Independent) (cont'd) 


CON Device Control Table 


Length 
Offset in Bytes Contents 


DWORD pointer to key- 
board remapping control 
table. 


Reserved 











Reserved 


Reserved 















AUX receive character buf- 
fer pointer. 


AUX receive character buf- 
fer length (bytes). 


AUX receive time out (sec- 
onds). 


AUX transmit time out (sec- 
onds). 


AUX baud rate (bits 3-0)* 
AUX parameters* 
Reserved 


AUX2 receive character buf- 
fer pointer. 









AUX2 receive character buf- 
fer length (bytes). 


AUX2 receive time out (sec- 
onds). 
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Table A-1 System Common Memory (I/O Version 
Independent (cont’d) 


AUX Device Control Tables (cont'd) 


Length 
Offset in Bytes Contents 


AUX2transmit time out (sec- 
onds). 


AUX2 baud rate (bits 3-0).* 
AU X2 parameters* 


Reserved 


AUX 3 receive character buf- 
fer pointer. 


AUX3 receive character buf- 
fer length (bytes). 


AUX3 receive time out (sec- 
onds). 


AUX3 transmit time out (sec- 
onds). 


AUX3 baud rate (bits 3-0)* 
AUX3 parameters* 


Reserved 





* The bit definitions for serial port baud rate and parameters 
correspond to those defined for CMOS memory switches 
A3FE:0002 and A3FE:0006. 


Note When the driver OPTRS232.SYS for the optional 
dual port RS-232C board is not installed, the AUX2 
and AUX3 receive character buffer pointers will be 
set to PPFEIPFFF. 
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Table A-1 System Common Memory (I/O Version 
Independent (cont’d) 


PRN Device Control Table 


Length 
Offset in Bytes Contents 


SO code 
SI code 
Reserved 


Code translation table. 


Reserved for alarm clock 
control table. 


Reserved 


Number of physical diskette 
drives. 


Number of diskette units de- 
fined by driver. 


Diskette drive O control 
block. 


Diskette drive 1 control 
block. 


Hard disk drive 0 control 
block. 


Hard disk drive | control 
block. 
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Table A-1 System Common Memory (I/O Version 
Independent (cont'd) 


Disk Control Block Format 


Length 
Offset in Bytes Contents 


Current controller sense 
Status. 







Current I/O command and 
options. 


Device address and unit. 











Parameter block for 
DISK_IO interrupt. 


Current return status from 
DISK_IO. 


Reserved 
Reserved 


Constant value block for cur- 
rent disk. 


MS-DOS BPB of. current 
disk. 


Reserved 









Parameter Block for DISK_IO Interrupt (Diskette) 


Length 
Offset in Bytes Contents 


Cylinder address 
Head address 


Sector address 









Sector length 

1/O data byte length 
I/O data buffer offset 
I/O data buffer segment 
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Table A-1 System Common Memory (I/O Version 
Independent (cont’d) 


Parameter Block for DISK_IO Interrupt (Hard Disk) 


Length 
Offset in Bytes Contents 


4 Sector address 

I/O data byte length 
1/O data buffer offset 
1/O data buffer segment 














Constant Value Block for Current Disk (Diskette) 


Length 
Offset in Bytes Contents 


Last cylinder address 
Last head address 


Last sector address 





l 
I 
I 
5 


Reserved 






Constant Value Block for Current Disk (Hard Disk) 


Length 
Offset in Bytes Contents 


Start sector address 





Last sector address 






4 
4 
| Number of partitions 
I 


Reserved 
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Table A-1 System Common Memory (I/O Version 
Independent) (cont’d) 


Configuration Table Format 


Length 
Offset in Bytes Contents 


CMOS (Battery-Backed Up) Memory Switches 





The APC III provides eight bytes of nonvolatile memory for 
storing certain system operating parameters. Information spe- 
cific to the particular hardware set can be configured in CMOS 
once. It will remain in effect until the contents of the CMOS 
are lost, or until they are changed. All necessary settings of 
these memory switches can be made via the APC III utilities; 
however, the maps in Figures A-2 through A-8 are available 
for programming information. 
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Nee eee eee ee ee 
XON/XOFF Protocol 
bitO = O: not used 
= 1: use XON/XOFF 

Data bits 

bit3,2 = 1,0: 7 bits 
1,1 : 8 bits 

Parity bits 

bit5,4 = 0,1: Odd 
1,1: Even 
X,0 : None 

Stop bits 


bit7.6 = 0,1: 1.0 bit 
1,0: 1.5 Bits 
1: 2.0 bits 


A3FE:0002 





Figure A-2 Parameters for Standard Serial Port (AUX) 





| Baud rate of AUX 


bit 3.2.1.0 
0.0.0.1: 75 bps 
0.0.1.0: 150 bps 
0,0,1,1 : 300 bps 
0,1.0,0: 600 bps 
0.1.0,1 = 1200 bos 
0,1,1,0 : 2400 bps 
0,1,1,1 : 4800 bps 
1,0,0,0 : 9600 bps 


Baud rate of AUX2 
same as above. 


Figure A-3 Baud Rate for Standard Serial Port (AUX) 
and First Optional Serial Port (AU X2) 
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A3FE:0A 





wee enn een ea GP em” 


| Start of RAMDISK 


bit 2,1,0 
0.0.0 : 128 KB 
0.0.1 : 256 KB 
0.1.0 : 384 KB 
0.1.1: 512 KB 
1.0.0 : 640 KB 


8087-2 
bit3 = O: not preser 
1: present 


Printer Data bits 
bit4 = O: 8 bits 
1:7 bits 


Printer interface 
bit5 = O: Centronics 
1: NEC ODA 


Display default color 
bit6 = O: white 


1: green 
Keyclick 
bit 7 = O: disable 
1: enable 


Figure A-4 Start of RAMDISK, 8087-2, Printer Data and 
Interface, and Default Display Color 
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XON/XOFF Protocol 
bitO = O: not used 
= 1: use XON/XOFF 


Data bits 

bit3,2 = 1,0: 7 bits 
1,1 2 8 bits 

Parity bits 

bit5.4 = 0,1: Odd 
1,1: Even 
X,0 : None 

Stop bits 

bit7,6 = 0,1: 1.0 bit 
10: 1.5 bits 
1,1 : 2.0 bits 


Figure A-5 Parameters for First Optional Serial Port (AU X2) 


ASFE-12 








Printer Data Pins 
bitO = O: 16 pins 


1: 24 pins 
RAM disk flag 
bit 1 = QO: disable 
1: enable 


Printer port select 
bit 3,2 
0.0 : parallel port 
0,1 « AUX 
1,0 : AUX2 
1,1 : AUX3 


Boot unit 

bit 7,6,5,4 
0.0.1.0 : Diskette 
1,0,1,0 : Hard disk #0 
1,0,1,1 : Hard disk #1 


Figure A-6 Printer Data Pins and Port, and RAMDISK 
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p7te{s}s]afz} sto) 


oe Printer type 
bit 4.3,2.1,0 

0,0.0.0,0 : no printer 
0,0,.0,0,1 : P2-3 
0,0.0;17.0 > Pa-3 
0,0.0.1,1 : 2050 
0,0,1,0,0 : 3530 
0.0.10 : 3350 
0.0.1.4: 7730 
O.0,1,1-1 ¢ 2036 
0.1,0,0,0 : Color Pinwriter 
0,.1,.0.0,1 : reserved 


A3FE:16 








1,.1,1,1.1 : reserved 


Reserved for future use 


Parallel printer parity 

bit 7.6 = 0.0: None 8 bit 
0.1 : Even 7 bit 
1,1 : Odd 7 bit 


Figure A-7 Printer Type and Parallel Printer Parity 


sree | 7 Lo] sts} a} z} sto 


eee Oe 


Year (yy) packed decimal 


Figure A-8 Year 
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ANSLSYS 
Escape Sequences 


ANSI Cursor Control Escape Sequences 
Conventions 
The following conventions are used throughout this appendix. 


1. The default value is used when no explicit value is given 
or a value of zero 1s used. 


2. Pnis used to specify a numeric parameter; for example, a 
decimal number specified with ASCII digit(s). 


3. Ps is used to specify a selective parameter. For example, 
any decimal number that is used to select a subfunction. 


Multiple subfunctions may be selected by separating the 
parameters with semicolons (;). 


Cursor Functions 
CUP — Cursor Position 
Eo. { Pils Pe 
HVP — Horizontal & Vertical Position 
ESC P12 Pet 
CUP and HVP move the cursor to the position specified by the 
parameters. The first parameter specifies the line number and 
the second parameter specifies the column number. The 


default value is one. When no parameters are supplied the 
cursor moves to the home position. 
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CUU — Cursor Up 

ESC [ PnA 
CUU moves the cursor up one or more lines without changing 
columns. The default value of Pn is one. This sequence is 
ignored if the cursor is already positioned on the top line. 
CUD — Cursor Down 

ESC [ PnB 
CUD moves the cursor down one or more lines without chang- 
ing columns. The default value for Pn is one. This sequence 1s 
ignored if the cursor is already on the bottom line. 
CUF — Cursor Forward 

BSC | Pat 
CUF moves the cursor forward one or more columns without 
changing lines. The default value for Pn is one. This sequence 
is ignored if the cursor is already in the rightmost column. 


CUB — Cursor Backward 
ESC [ Pn D 


CUB moves the cursor backward one or more columns with- 
out changing lines. The default value for Pn is one. This 
sequence is ignored if the cursor is already in the leftmost 
column. 
DSR — Device Status Report 

ESC [ 6n 


The console driver will output a CPR sequence on receipt of 
DSR. 


CPR — Cursor Position Report 
ESC t Pn: Pa KR 
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The CPR sequence reports current cursor position via stan- 
dard input. The first parameter specifies the current line and 
the second parameter specifies the current column. 

SCP — Save Cursor Position 


ESC [ s 


The current cursor position is saved. This position can be 
restored with the RCP sequence. 


RCP — Restore Cursor Position 
ESc. |. 3 
RCP restores the cursor position to the value it had when the 
console driver received the SCP sequence. 
Erasing Functions 
ED — Erase Display 
Est | 2 


Erases all of the screen and the cursor returns to home 
position. 


ESC[ J or ESC[ 0J 


Erases from the cursor to the end of the screen, including the 
cursor position. 


ESC [ 1J 


Erases from the start of the screen to the cursor, including the 
cursor position. 


EL — Erase Line 
ESC | K or ESC [ 0K 


Erases from the cursor to the end of the line, including the 
cursor position. 


ESC [1K 
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Erases from the start of the line to the cursor position, includ- 
ing the cursor position. 


ESC [ 2K 


Erases all of the line including the cursor position. 


Modes of Operation 
SGR — Set Graphics Rendition 
ESC) | Pss.c3 Ps m 


SGR invokes the graphic rendition specified by the parame- 
ter(s). The following characters in Table B-I are rendered 
according to the parameter(s) until the next occurrence of 
SGR. 


Table B-1 SGR Parameters 


Parameter Parameter Function 


All attributes off 

Underscore on 

Blink on 

Reverse video on 

Concealed on (ISO 6429 standard) 
Black foreground (ISO 6429 standard) 
Red foreground (ISO 6429 standard) 
Green foreground (ISO 6429 standard) 
Yellow foreground (ISO 6429 standard) 
Blue foreground (ISO 6429 standard) 
Magenta foreground (ISO 6429 standard) 
Cyan foreground (ISO 6429 standard) 
White foreground (ISO 6429 standard) 





SM — Set Mode 


Note The SM escape sequence is not an ANSI standard. 
It is only applicable to NEC and MicroSoft. 
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The possible control sequences are: 


ESC [ 
ESC [ 
ESC [ 


h 
Oh 
ESC [27h 


ee ee ee 


The ESC [ ? sequence applies to end of line only. SM invokes 
the screen width or type specified by the parameter. Table B-2 


Ps h 


lists the available set modes. 


0 


I 
Z 
3 
4 
5 
6 
7 
8 
9 
0) 


_— 


Table B-2 Set Modes 


40 x 25 black and white 
40 x 25 color 

80 x 25 black and white 
80 x 25 color 

320 x 200 color 

320 x 200 black and white 
640 x 200 black and white 
Wrap end of line 

640 x 200 color 

640 x 400 black and white 
640 x 400 color 


ESC [>5h 


Enables cursor display. 


RM — Reset Mode 


The possible control sequences are: 


ESC [ = Ps 1 
ESC [ =1 
ESC [ =0 
ESC [29 


Parameter Function 


Text 
Text 
Text 
Text 
Graphics 
Graphics 
Graphics 


Graphics 
Graphics 
Graphics 





Parameters are the same as SM (Set Mode) except that 
parameter 7 will reset wrap at end of line mode. The character 
“I”? is a lower case letter and not the number I. 


ESC [ >51 


Disables cursor display. 
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Keyboard Reassignment 


Although the APC III keyboard reassignment is not part of the 
standard ANSI 3.64-1979 and ISO 6429, it is performed ina 
compatible manner. 


The possible control sequences are: 


ESC [ Pn; Pn:.. Pop 
ESC [ “string”; p 
FSC [ Pn: “string”: Pos Pn: “string”: Pu p 


or any other combinations of string and decimal numbers. 


The final code in the control sequence (“p”) is reserved for 
private use by the ANSI 3.64-1979 standard. 


The first ASCII code in the control sequence defines which 
code is being mapped. The remaining numbers define the 
sequence of ASCII codes generated when this key 1s inter- 
cepted. 


There is one exception. If the first code in the sequence Is zero 
(NUL), then the first and second code make up an extended 
ASCII redefinition. Refer to Appendix H for a list of all the 
ASCII and extended ASCII codes. 


Following are two examples of keyboard reassignment using 
control sequences. 


1. Reassign the Q and q key to the A and a key, and then 
reassign them to their original values. 


ESC. | 6326-1 p A becomes Q 
BSC | 97slisp a becomes q 
ESC [| 8 1;63p Q becomes A 
ES. | Lise 7p q becomes a 


2.  Reassign the F10 key toa DIR command followed bya 
Carriage return. 


Fs | USTO73 "air": 1 3p 


The 0; 107 is the extended ASCII code for the F10 key; 13 
decimal is a carriage return. 
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APC ITI/MS-DOS Interrupt 
Vector Assignments 






The 8086 processor reserves the lowest 1024 bytes of memory 
for 256 interrupt vectors. Each interrupt vector contains a 
double word (4-byte) address consisting of an offset followed 
by a segment. The interrupt vector contents are used by the 
processor as the address of the routine assigned to handle an 
interrupt. 


Interrupt Levels 


Many interrupt levels (and the vectors associated with them) 
are reserved for special uses 1n the APC III. The 8086 proces- 
sor, APC III hardware, ROM BIOS, MS-DOS operating 
system, GSX, and GW BASIC Interpreter reserve some of the 
interrupt levels. 


The 8259 interrupt controller level 0 interrupt is attached to the 
8086 interrupt level 8, 8259 level | is attached to the 8086 level 
9, and so forth. Note that the 8259 interrupt levels are mapped 
into the 8086 interrupt levels starting with 8086 level 8 (timer 
interrupt). Table C-1 lists the interrupt levels and their 
reserved uses. 


SC-1 


Interrupt Vector Assignments 


Table C-1 Interrupt Levels 


Vector 
Address 
(hex) 


0000:0000 
0000:0004 
0000:0008 


0000:000C 
0000:0010 
0000:0014 


0000:0018 
0000:001C 
0000:0020 
0000:0024 
0000:0028 
0000:002C 
0000:0030 
0000:0034 
0000:0038 
0000:003C 
0000:0040 
0000:0044 
0000:0048 
0000:004C 
0000:0050 
0000:0054 
0000:0058 
0000:005C 
0000:0060 
0000:0064 
0000:0068 
0000:006C 
0000:0070 
0000:0074 
0000:0078 
0000:007C 
0000:0080 
0000:0084 
0000:0088 
0000:008C 


Reserved Function 


Divide by zero (8086) 

Single step (8086) 

Non-maskable interrupt (NMI) 
(8086) 

Breakpoint instruction (8086) 

Arithmetic overflow (8086) 

CRTDUMP activation 
(MS-DOS CRTDUMP) 

Gets control on keyboard break* 

Gets control on timer interrupt* 

Timer interrupt 

Keyboard interrupt 

CRT interrupt** 

Extended bus INTO** 

RS-232 interrupt 

Extended bus INT1** 

Extended bus INT2** 

Reserved** 

Printer interrupt** 

Extended bus INT3** 

Diskette interrupt 

Extended bus INT4** 

Extended bus INT5** 

Extended bus INT6** 

8087 APU interrupt 

Reserved ** 

Keyboard I/O call (ROM BIOS) 

CRT I/O call (ROM BIOS) 

RS-232C I/O call (ROM BIOS) 

Printer I/O call (ROM BIOS) 

Timer I/O call (ROM BIOS) 

Disk I/O call (ROM BIOS) 

OPTRS232 I/O call 

Reserved 

MS-DOS program terminate 

MS-DOS function call 

MS-DOS terminate address 

MS-DOS CTRL-BREAK exit 
address 
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Table C-1 Interrupt Levels (cont’d) 


Vector 


Address Reserved Function 
(hex) 


0000:0090 MS-DOS fatal error vector 

0000:0094 MS-DOS absolute disk read 

0000:0098 MS-DOS absolute disk write 

0000:009C MS-DOS terminate, fix in 
storage 

0000:00A0 Background process entry 

0000:00A4 Reserved for MS-DOS 


0000:00FF | Reserved for MS-DOS 
0000:0100 Not used 


0000:0380 | GSX function call 


0000:03FF | Not used 





*Initialized at power up to point to an IRET instruction. 


**] nitialized at power up to point to an EOI process. 
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Extended Bus Interrupt Vectors 


Many of the APC III expansion options use the extended bus 
interrupt vectors. Table C-2 shows the INTs that are available 
for each option. In order to avoid conflicts, you should make 
sure that each option operates on a unique INT; that is, a 
particular INT is not used for more than one option. Most of 
the options can choose from among several INTs, but for the 
hard disk controller, only one choice is available. Factory 
settings are indicated, where applicable. 


Table C-2 Extended BUS INT Usage 


Option and Kit Number INT2| INT3 INTS | INT6 


Joystick /Sound Card 
APC-H152 


General Purpose Interface Bus 
APC-H150 


Additional Serial 

Interface Card APC-H156 
First Optional Port (AUX2) 
Second Optional Port (AUX3) 


10 MB Hard Disk 
APC-H112, APC-H170, APC-H171 


PC-UX Memory Management Card 
APC-H155 





* Indicates factory setting. 


** Factory set, cannot be changed. 
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Vectors with Special Meanings 


Following are explanations of vectors that have special 
meanings. 


INTERRUPT 06H — Keyboard Break Address 


The Keyboard Break Address points to the code to be exer- 
cised when you press <Ctrl> and <Break Stop>. The vector is 
invoked while responding to the keyboard interrupt. Control 
should be returned via the IRET instruction. The power on 
routines initialize this vector to point to an IRET instruction. 
This ensures that nothing happens when you press <Ctrl> and 
<Break Stop> unless the application program sets a different 
value. Control may be retained by this routine, if the break 
occurred during interrupt processing. 


INTERRUPT 07H — Timer Internal Process Address 


The timer internal process address vector points to the code to 
be executed after every time interval. This vector is invoked 
while responding to the TIMER I/O. Control should be 
returned via an IRET instruction. The power on routines 
initialize this vector to point to an IRET instruction. This 
ensures that nothing happens unless the application modifies 
the pointer. It is the application’s responsibility to save and 
restore all registers to be modified. 
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CONFIG.SYS 
Configuration File 






Configuration Files in MS-DOS V. 2.0 and Higher 


In many cases, there are installation-specific configurations of 
the DOS that need to be set up at boot time. It is considered a 
poor design for a user/OEM to have to rebuild MS-DOS in 
order to include special device drivers, or a number of device 
drivers. The configuration file allows you to configure the 
system without extra work. 


The configuration file is simply an ASCII file that has certain 
commands for the bootstrap. The bootstrap process follows. 


L 


The disk boot sector is read. The sector contains enough 
code to read the DOS and initial BIOS. 


The DOS and initial BIOS are read. 


A long jump is made tothe BIOSINIT routine. A variety 
of BIOS initializations are performed. 


A long jump is made to the SYSINIT routine in the 
SYSINIT module. This module (supplied by Microsoft) 
initializes the DOS and reads the CONFIG.SYS file. If 
CONFIG.SYS exists, it performs device installations and 
other user-settable options. 


Its final task is to EXEC the command interpreter, which 
completes the bootstrap process. 
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CONFIG.SYS Commands 


The following is a list of commands that can appear in the file 
CONFIG.SYS. 
BUFFERS = <number> 
This is the number of additional sector buffers to add to 
the system list. The effect of several BUFFERS com- 
mands is to allocate a series of buffers. 
FILES = <number> 
This is the number of open files that the XENIX system 
calls can access. 
DEVICE = <filename> 
This installs the device driver in <filename> into the 
system list. 
BREAK = <ON or OFF> 


If ON is specified (the default is OFF), a check for “C at 
the console input will be made every time the system 1s 
called. ON improves the ability to abort programs over 
previous versions of the DOS. 


SHELL = <filename> 


This begins execution of the shell (top-level command 
processor) from <filename>. 


A typical configuration file might look like this: 


BUFFERS = 10 


FILES = 10 
DEVICE = \bin\network.sys 
BREAK = ON 


SHELL = a:\bin\command.com a:\bin /p 


The default value for BUFFERS in the APC III I/O system 1s 
2. The minimal value is one. The default value for FILES is 8, 
so “FILES = 10” would actually allocate only two new file 
channels. If a number less than or equal to 5 1s specified, the 
command is ignored. The default value for BREAK is off. 
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ROM BIOS Function Calls ¢4_=8= 







This Appendix gives a summary of all the ROM BIOS calls 
available to the programmer. For more extensive information 
on ROM BIOS calls, refer to the APC I/] System Reference 
Guide and the ROM BIOS lists available on diskette. 


Note Programmers should not presume any register pres- 
ervation or make ROM BIOS calls with undocu- 
mented parameters, as the results are unpredictable. 


KEYBOARD_IO Call 


KEYBOARD_IO 


Calling Sequence 


Input 


(AH)=0 


(AH)=1 


18H 


MOV AH, FUNCTION; (see below for subfunction 
numbers). 


INT KEYBOARD_IO; I8H 


Read the next ASCII character from the keyboard 
FIFO queue. 


Return with the result in(AL), scan code in(AH). If AL 
is 0, then the Extended ASCII code is returned in AH. 


Set the Z flag to indicate whether an ASCII character is 
available to be read from the FIFO queue. 


(ZF)=1 Nocode is available. The queue is empty. 


(ZF)=0 Codeisavailable. There is at least one charac- 
ter in the queue. The next character read from the FIFO 
queue is returned in AL and the key’s scan code is 
returned in AH unless the key produces an extended 
ASCII code. In this case, AH will contain the second 
code returned for the key and AL will always contain 
OOH. 
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(AH)=2 Returns the current shift status in the AL register. The 

bit settings for this code are as follows: 

bit 7(/(MSB)=1 Insert state is active. 

bit 6 =1 <Caps Lock> state has been 
toggled. 

bit S=1 <Grph I> lock state has been 
toggled. 

bit 4=1 <Grph 2> lock state has been 
toggled. 

bit 3=1 <Alt> shift key pressed. 

bit 2=1 <Ctrl> shift key pressed. 

bit 1=1 <Shift> key pressed. 

bit 0(LSB)=1 <Fnc> shift key pressed. 

CRT_IO Call 
CRT_IO 19H 


Calling Sequence MOV AH, FUNCTION 
INT CRT_IO; 19H 


Note Inthe CRT_IO functions, registers CS, SS, DS, ES, 
BX, CX, and DX are preserved in the call. All other 
registers are destroyed. 


Input 


(AH)=0 Set a display mode. (AL) contains the mode value. The 
following modes are available. 


Text modes 


(AL)=0 40 25 monochrome (master GDC) 
(AL)=1 40 25 color (master GDC) 
(AL)=2 80% 25 monochrome (master GDC) 
(AL)=3 80 25 color (master GDC) 


Graphic modes 


(AL)=4 320 200 color (slave GDC) 
(AL)=5 320 200 monochrome (slave GDC) 
(AL)=6 640 x 200 monochrome (slave GDC) 
(AL)=7 640 200 color (slave GDC) 
(AL)=8 640 = 400 monochrome (slave GDC) 
(AL)=9 640 x 400 color (slave GDC) 
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Whenever a new mode is selected, the entire screen is 
cleared. Modes 8 and 9 are used for CRT monitor 
displays only. CRT_IO does not care what the present 
CRT mode is. If a color graphics mode is specified, 
CRT_IO checks the color graphics board (VRAM). If 
there is no color graphics board, the mode is changed 
automatically from color to black and white. If modes 
5,6, or 8 are specified, CRT_IO sets the palette color ID 
to the fixed value. 


Note After making this call, users must delay writing to text 
or graphics VRAM for approximately 65 milliseconds 
to avoid corruption of displayed data. 

GDC has two screen pages in both text and graphics 


modes. The row and column positions are defined as 
follows. 


0 <®X1 or X2x% 319 0r 639 


199 or 
399 


Text Graphics 


Set cursor type. 


(CH)=2 and (CL)=5, the following cursor type will be 
displayed. 













Sea aRERaE 
SRR ERERE 
a EEE Ea EE 
lel ele lela e le 
FEE Ea Ea Ea Ea Ec 
OE Ea Ea Ea EE Ea 


<4 start line 2 (CH) 


<<." end line 5 (CL) 
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(AH)=2 


(AH)=3 


(AH)=4 


(AH)=5 


(AH)=6 


(AH)=7 


(CH) and (CL) must be below 7. 


If bit 4 of the CH register is set to 1, the cursor will not 
blink. If the MSB (bit 7) of CH is set to 1, the cursor 
display will be disabled. 


Set cursor position 
(DH, DL) = Row, column; (0,0) is upper left 
(BH) = Page number, (0,1) 


Read cursor position 
(BH) = Page number, (0,1) 


On exit, 
(DH), DL) = Row, column of current cursor. 


(CH), CL) = Cursor type (same as set cursor type 
function). 


Reserved for future use. 


Select active display page. 
(AL) = New page value (0 or 1). 


Scroll active page up. 


(AL) = Number of lines, input lines blanked at 
bottom of window. AL=0 indicates blank 
entire window. 


(BH) = Attribute to be used on blank line (text 
mode). Color ID to be used on blank line 
(graphics mode). 


(CH, CL) = Row, column of upper left corner of win- 
dow to scroll. 


(DH), DL) = Row, column of lower right corner of 
window to scroll. 


A space code is used on blank lines in the text modes. 


Scroll active page down 


(AL) = Number of lines, input lines blanked at 
top of window. AL=0 indicates blanked at 
top of window. 


(BH) = Attribute to be used on blank line (text 
mode). Color ID to be used on blank line 
(graphics mode). 


SE-4 


ROM BIOS Function Calls 


(CH, CL) = Row, column of upper left corner of win- 
dow to scroll. 


(DH, DL) = Rowcolumn of lower right corner of win- 
dow to scroll. 


Character 
Handling 
Functions 
(AH)=8 Read attribute/character at current cursor position. 
(BH) = Display page. 
On exit, 
(AL) = Character read. 
(AH) = Attribute of character read (text). 
The current cursor position is not changed. 
(AH)=9 Write attribute/character at current cursor position. 


(BH) = Display page. 
(CX) = Count of characters to write. 
(AL) = Character to write. 


(BL) = Attribute of character (text). 
= Palette number (graphics). 


The palette number includes the operational codes as 
shown in Figure E-1. 


7istststst2tsfo 
ee Fe” 


wee 


-_ Palette color-ID 


bit 2 controls green 
bit 1 controls red 
bit O controls blue 


Operation code 


bit 7,6 
0,0 : replace 
0,1 : complement 
1,0 : clear 
1,1: set 


Figure E-1 Palette Numbers and Codes 
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(AH)=10 


Graphics 
Interface 


(AH)=11 


(AH)=12 


(AH)=13 


Write character only at current cursor position. 


(BH) = Display page. 

(CX) = Count of characters to write (not equal to 0). 
(AL) = Character to write. 

(BL) = Palette number (graphics). 


The replication factor contained in (CX) will only pro- 
duce valid results for characters on the same row in the 
graphics writer character interface. Continuation to 
succeeding lines will be produced incorrectly. 


Set color palette 
(BH) = Palette color ID being set (0-7). 
(BL) = Color value used with color ID (0-7). 


Write dot. 

(DX) = Row number. 
(CX) = Column number. 
(AL) = Palette number. 


Bit 7 and 6 of AL are used as MOD for the 
uPD7220 GDC: 


00 - replace 
01 - complement 
10 - clear 
11 - set 
Read dot. 


(DX) = Row number. 
(CX) = Column number. 


On exit, 


(AL) = Returns palette number. In monochrome 
modes (AL) = 0 or 1, black is 0. 
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ASCII teletype 
routine for 


output 
(AH)=14 Write teletype. 
(AL) = Character to write. 
(BL) = Palette number (graphics only). 
The available ASCII control characters are as 
follows: 
07h — Bell 
08h — Back Space 
0Ah — Line Feed 
0Dh —~ Carriage Return 
In the text modes, the space code is used as a 
filling character when you scroll. Previous cursor 
position’s attribute is used as the attribute of the 
filling character. 
In graphic modes, the current active display page 
is used (BH). The lowest three bits used for 
palette numbers are 0),0,0. 
(AH)=15 Current CRT state. 
On exit, 
(AL) = Mode currently set. 
(AH) = Number of character columns on screen. 
(BH) = Current active display page. 
CS, SS, DS, ES, BX, CX, and DX are preserved 
during the call. All others are destroyed. 
Slave GDC 
Functions 
Note The following functions are not supported in the 
320 x 200 character graphics mode. 
(AH)=16 Set draw mode function 


(AL) = 0: Flash draw. 
(AL) = 1 : Flashless draw (default mode). 
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(AH)=17 


(AH)=18 


(AH)=19 


(AH)=20 


Set draw page function 


(AL) = Page number (0 or I; default is 0). The 
specified page is used in the following 
functions. 


(AL) = 12: Write dot functions. 

(AL) = 13: Read dot functions. 

(AL) = 18: Clear graphic screen function. 
(AL) = 19: Draw line function. 

(AL) = 20: Draw rectangle function. 
(AL) = 21: Tile rectangle function. 

(AL) = 22: Draw circle function. 


Clear graphics screen function 


(AL) = Palette number (not included in opera- 
tional code). 


Draw line function 
(AL) = Palette number. 


(BX) = Line pattern (must be a 16-bit 
pattern). 


(SI, DI) = (X1,Y1) point 1 
(CX, DX) = (X2,Y2) point 2 


Draw rectangle function 
(AL) = Palette number. 
(BX) = Line pattern. 

(SI, DI) = (X1,Y1) point 1 
(CX, DX) = (X2,Y2) point 2 


(X1,Y1)————»> 





(AH)=21 


Tile rectangle function 

(SI, DI) = (X1,Y1) point | 
(CX, DX) = (X2,Y2) point 2 
(ES:BX) = Tile pattern pointer 
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(AH)=22 





ROM BIOS Function Calls 


(8 bytes) 


(8 bytes) 


(8 bytes) 


Tile pattern (each plane has 8 bytes) 


t 2 2 4 6 6 7 LSB (bit 0 is on the left side) . 


X 3 planes 


Draw circle function 


(AL) = Palette number. 


(BX) = Line pattern. 
(SI) = Radius. 
(CX, DX) = Center of circle (X1,Y1). 
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ae 


<< S| 


In the 640 x 200 character modes, an ellipse is drawn. 
Also, complement operation code in (AL) 1s not sup- 
ported. 


RS232C_I10O Call 


RS232C_10O 1AH 


Calling Sequence MOV AH, FUNCTION 
INT RS232C_I10;1 AH 


Input 
(AH)=0 Initialize RS-232C. 
(AL) Baud Rate, 
0- 75 bps 
| - 150 bps 
2- 300 bps 
3- 600 bps 
4- 1200 bps 
5 - 2400 bps 
6 - 4800 bps 
7 - 9600 bps 


(CH) Asynchronous mode for uPD 8251A 
bit 7,6: Stop bit length 

Ol - 1 bit 

10 - 1.5 bit 

1] - 2 bit 
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bit 5, 4: Parity 


XO - none 
01 - odd 
11 - even 
bit 3, 2: Word length 
00 - 5 bits 
Ol - 6 bits 
10 - 7 bits 
11 - 8 bits 
bit 1, 0 : Clock 
10 - x16 
11 - x64 


(CL) Command for uwPD8251A 


bit 6: Interrupt reset 

bit 5 : Request to send 

bit 4: Error request 

bit 3: Send break character 
bit 2: Receive enable 

bit 1: DTR on 

bit 0 : Send enable 


(ES:DI) Receive buffer pointer 
(DX) Receive buffer byte length 


(BH) Time out second on send; a value of 0 sets the 
default. 


(BL) Time out second on receive; a value of 0 sets the 
default. 


Note  Theselection of 0 (default) time out values in the initial- 
Ize RS-232C function calls (set in registers BH and BL) 
will result in the selection of “infinite” (no) time out 
values for the RS232C_IO ROM BIOS functions. 


On exit, 


(AH) Return Code 

0 - Normal exit 

| - Not available 

2 - Receive buffer overflow 

3 - Send disable) receive disable 


(AH)=1 Initialize RS-232C for X ON/OFF protocol. 


AL, CH, CL, ES:DI, DX, BH, BL, (same as initialize 
RS-232C (AH)=0). 


On exit, 


(AH) Return code same as initialize RS-232C. 
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(AH )=2 Get data length in receive buffer. 


On exit, 
(AH) Return code. 
(CX) Data length. 


(AH)=3 Send a character in (AL). 


On exit, 


(AH) Return code same as initialize RS-232C. 
(AH )=4 Receive character from receive buffer. 


On exit, 
(AH) Return code 
(CH) Receive character 


(CL) Line status on receive 
bit 7: Data set ready 

bit 6: SYNC detect 

bit S : Framing error 

bit 4: Data overrun 

bit 3: Parity error 

bit 2: Transmitter empty 
bit | : Clear to send 

bit 0 : Carrier detect 


(AH)=5 Command tor wPD8&251A. 
(AL) uP D8251A (see the Initialize RS232-C (CL) 


On exit, 


(AH) Return code 
(AH)=6 Get status in (CH) and (CL). 


On exit, 
(AH) Return code 


(CH) uwPD8251A status 
bit 7: Data set ready 

bit 6: SYNC detect 

bit 5: Framing error 

bit 4: Data overrun 

bit 3: Parity error 

bit 2: Transmitter empty 
bit | : Receive ready 

bit 0: Transmit ready 
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(CL) Port status. 
bit 7: Ring indicator 0: activated 


1: deactivated 
bit6: Cleartosend 0: enabled 

|: disabled 
bit 5 * Carrier detect 0: detected 

|: nondetected 


PRINTER_IO Call 


PRINTER_IO IBH 


Calling Sequence MOV AH, FUNCTION 
INT PRINTER_IO; IBH 


Input 
(AH )=0 Print a character in (AL) 
On exit, 
(AH) Status 
(AH)=1 Initialize the printer port. 
On exit, 
(AH) Status 
bit 1, 0 
00 - printer ready 
Ol - printer not ready 
10 - time out 
11 - power off or not on-line 
(AH)=2 Read the printer status into (AH). 
(AH)=3 Print n character in data buffer. 


(ES:BX) Data buffer pointer. 
(CX) Print data length 


On exit, 


(AH) Status. 
(AH)=0 for normal end. 


(BX) Data pointer offset at time out state. 
(CX) Remaining data length. 


(BX) and (CX) are set if return status (AH) is not equal 
to 0. 
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ROM BIOS Function Calls 


TIMER_IO Call 


TIMER_IO ICH 


Calling sequence MOV AH, FUNCTION 
INT TIMER_IO; ICH 





Input 
(AH)=0 Get date and time. 
(ES:BX) Date and time data buffer pointer. 
On exit, 
date and time into data buffer 
0 Packed decimal value 
1 Binary, and stored in upper 4 
bits of the byte. November = BXH 
Z 
3 
: 
: 
(AH)=1 Set date and time. 
(ES:BX) Date and time data buffer pointer. Same as 
(AH)=0. 
(AH)=2 Set interval timer. 


(CX) Interval time (10 msec. ~ 65536 msec.) 
(ES:BX) time out interrupt pointer. 
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DISK_IO Call 


DISK_IO 


Calling sequence 


Command 
options 


1DH 


MOV 
MOB 
MOV 
MOV 
MOV 
MOV 
MOV 





ROM BIOS Function Calls 


AH, COMMAND_OPTION 
AL, DEV_UNIT_OPTION 
BX, DATA_LENGTH 

Cx, CYLINDER_SECTOR 
DH, HEAD_NUMBER 
DL, SECTOR_NUMBER 


ES, (buffer segment)* 
BP, (buffer offset)* 


INT DISK_IO;1DH 


*If vouspecify an odd address for | O buffer offset, the 
DMA transfer will be slower. To avoid this specify an 
even memory address for! O buffer offset. The DMA 
Operation ts limited to within a 64 K byte memory 
bank. Check that the buffer does not exceed the 64 K 
byte boundary. 


(AH) 
bit 7: 


bit 6: 


bit S: 


bit 4: 


Track access option 

0 - single track 

| - multitrack 

Density option 

0 - single density 

| - double density 

Error retry on track option 
0 - 8 retry 

| - no retry 

Seek option 

0 - no seek performed 

| - seek before command 
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ROM BIOS Function Calls 


bit 3,2, 1, 0: 
0000 - no operation 
0001 - verify data 
0010 - read diagnostics 
0011 - initialize 
0100 - sense 
0101 - write data 
0110 - read data 
O11ll - recalibrate 
1000 - no operation 
1001 - write deleted data 
1010 - read ID 
1011 - no operation 
1100 - read deleted area 
1101 - write ID 
1110 - no operation 
1111 - retract (hard disk) 


(AL) Device drive unit and option 


Option: 
bit 7: Relative sector access on hard disk. 
bit 6 : Double-track access on diskette. 
Disk type: 
bit 5,4 

00 - 5'4 Diskette 

01 -5'4 Hard disk 
bit 3, 2, 1, 0; Unit number. 

0000 - Unit number 0 

0001 - Unit number | 


(CH) Sector length for diskette. 
Q- 128 byte/sector 
| - 256 byte/sector 
2- 512 byte/sector 
3 - 1024 byte/sector 


(CL) Cylinder number for diskette. 
(DH) Head number for diskette. 
(DL) Sector number for diskette. 


Hard disk parameters 
If bit 7 of (AL) = | 

(CX) Relative sector number (low) 

(DX) Relative sector number (high) for hard disk 
If bit 7 of (AL) = 0 

(CX) Track number 

(DX) Sector number for hard disk 


On exit, 


(C-flag) First status. 
0 - Successful end 
1 - Unsuccessful end 
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Second status 


ROM BIOS Function Calls 


(AH) 

bit 7, 6, 5, 4; Access status. 
0000 - Normal end (C-flag = 0) 
0001 - Control mark (C-flag = 0) 
0010 - DMA boundary (C-flag = 1) 
0011 - End of cylinder (C-flag = 1) 
0100 - Not ready (C-flag = 1) 
0101 - Not writable (C-flag = 1) 
0110 - Equipment check (C-flag = 1) 
0111 - Equipment check on seek (C-flag = !) 
1000 - Over run (C-flag = 1) 
1001 - Time out (C-flag = 1) 
1010 - Data error (ID) (C-flag = 1) 
1011 - Data error (data) (C-flag = 1) 
1100 - No data (C-flag = 1) 
1101 - Bad cylinder (C-flag = 1) 
1110 - Missing address (ID) (C-flag = 1) 


bit 1, 0; Hard disk type on sense command to 
hard disk 
01-10 MB hard disk 

bit 0; Diskette type on sense command to FD. 


0 - Double-sided double-density (2D) 


OPTRS232C_IO Call 


OPTRS232C_IO 


Calling Sequence 


Input 


(SI) 


(AH)=0 


IEH 


MOV AH, FUNCTION 
INT OPTRSZ32C_IO ; [EH 


For all calls, (SI) indicates the port being used. 


0 - Use AUX port (pass call to INT IA) 
| - Use AUX2 port 
2 - Use AUX3 port 


Initialize RS-232C. 
(AL) Baud Rate, 


O- 75 bps 
| - 150 bps 
2- 300 bps 
3 - 600 bps 
4 - 1200 bps 
5 - 2400 bps 
6 - 4800 bps 
7 - 9600 bps 


col as 


ROM BIOS Function Calls 


Note 


(CH) Asynchronous mode for uPD8251A 
bit 7,6: Stop bit length 


01 - 1 bit 
10 - 1.5 bit 
11 - 2 bit 
bit 5, 4: Parity 
XO - none 
01 - odd 
1] - even 
bit 3, 2: Word length 
00 - 5 bits 
01 - 6 bits 
10 - 7 bits 
11 - 8 bits 
bit. 1, 0: Clock 
10 - x16 
11 - x64 


(CL) Command for wPD8&25I1A 


bit 6: Interrupt reset 

bit 5 : Request to send 

bit 4: Error request 

bit 3: Send break character 
bit 2: Receive enable 

bit |: DTR on 

bit 0 : Send enable 


(ES:D1) Receive buffer pointer 
(DX) Receive buffer byte length 


(BH) Time out second on send; a value of 0 sets the 
default. 


(BL) Time out second on receive; a value of 0 sets the 
default. 


The selection of 0 (default) time out values in the initial- 
ize RS-232C function calls (set in registers BH and BL) 
will result in the selection of “infinite” (no) time out 
values for the OPT RS232C_IO ROM BIOS functions. 


On exit, 


(AH) Return Code 

0 - Normal exit 

1 - Not available 

2 - Receive buffer overflow 

3 - Send disable/ receive disable 
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ROM BIOS Function Calls 


(AH)=1 Initialize RS-232C for X ON/OFF protocol. 


AL, CH, CL, ES:DI, DX, BH, BL, (same as initialize 
RS-232C (AH)=0). 


On exit, 
(AH) Return code same as initialize RS-232C. 


(AH)=2 Get data length in receive buffer. 


On exit, 
(AH) Return code. 
(CX) Data length. 


(AH)=3 Send a character in (AL). 


On €xit, 
(AH) Return code same as initialize RS-232C. 


(AH)=4 Receive character from receive buffer. 


On exit, 
(AH) Return code 
(CH) Receive character 


(CL) Line status on receive 
bit 7: Data set ready 

bit 6: SYNC detect 

bit 5 : Framing error 

bit 4: Data overrun 

bit 3: Parity error 

bit 2: Transmitter empty 
bit | : Clear to send 

bit 0 : Carrier detect 


(AH)=5 Command for wPD8251A. 
(AL) uwPD8251A (see the Initialize RS232-C (CL)) 


On exit, 
(AH) Return code 
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ROM BIOS Function Calls 


(AH)=6 Get status in (CH) and (CL). 


On exit, 
(AH) Return code 


(CH) uwPD8251A status 
bit 7: Data set ready 

bit 6: SYNC detect 

bit 5 : Framing error 

bit 4: Data overrun 

bit 3: Parity error 

bit 2: Transmitter empty 
bit | : Receive ready 

bit 0: Transmit ready 


(CL) Port status. 
bit 7: Ring indicator 0: activated 

1: deactivated 
bit 6: Clear to send 0: enabled 

1: disabled 
bit 5: Carrier detect 0: detected 

I: nondetected 
bit 1: ILI (see chart for values) 
bit 0: I1L2 (see chart for values) 


Interrupt Assignment 


AUX2 AUX3 
INTO (I1R3) INTO (IR3) 


INTI (IRS) INT4(IR11) 


INT2 (IR6) INTS(IR12) 


INT3 (IR9) INT6(IR13) 
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Appendix F 4 
CRT Display Character Set —_= 





Figure F-1 illustrates the displayable character set for the APC 
III. The two digit hexadecimal code for any character can be 
found by taking the number inthe top rowas its first digit, and 
the number in the left column as its second digit. The charac- 
ters are defined by the contents of an internal hardware 
character-generator ROM. The figure defines the graphics 
that display when the corresponding code is written into a 
character position in the VRAM memory. 


Certain characters cannot be displayed through the CON 
device driver because they have special meanings. For exam- 
ple, the character code 13 (decimal) is reserved for Carriage 
Return. The console driver will intercept the character, and act 
on it, rather than place it into VRAM. 
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Figure F-1 The APC III Displayable Character Set 
SF-1 
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VRAM CRT Display 











Text VRAM Memory Map 


The standard APC III 1s equipped with 8 K bytes of standard 
text VRAM. Table G-1 lists how the memory address space is 
situated in the 8086 MPU. 


Table G-1 MPU Memory Address Space 


A000:0000-A000:0F9F Page | character codes 


A000: 1000-A000:1F9F Page 2 character codes 
A000:2000-A000:2F9F Page | character attributes 
A000:3000-A000:3F9F Page 2 character attributes 





Within each display area, the mapping of MPU memory 
address to screen positions is listed in Table G-2. The examples 
use the address space for Page | character codes, but the 
mapping also applies to the other regions (Page 2 characters 
and attributes). 
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VRAM CRT Display 


Table G-2 Mapping of MPU Memory Addresses 


MPU Text Display Mode 
Address 80 x 25 40 = 25 


A000;0000 : : (displayed char. pos.) 
A000;0001 x = unused 
A000;0002 

A000;0003 

A000:0004 

A000:0005 

A000:0006 

A000:0007 

A000:0008 

A000:0009 


A000:009C 
A000:009D 
A000:009E 
A000:009F 
A000:00A0 
A000:00A | 
A000:00A2 
A000:00A3 
A000:00A4 
A000:00A5 
A000:00A6 


A000:0F9C | (25,79) (25, 40) 


A000:0F9D x X 
A000:0F9E (25, 80) x 
A000:0F9F x * 





Text Mode Attributes 


Each character in the APC II] text VRAM has a correspond- 
ing attribute byte (located 2000H bytes above the character). 
Each bit in the attribute byte specifies whether the character 
will be displayed with a particular attribute. By combining bits 
in the attribute byte, combinations of attributes for a given 
display character can be achieved. 
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VRAM CRT Display 


The format of the attribute byte follows. 


Bit 7 (high order) Green 
6 Red 
5 Blue 
4 Vertical Strike Through Standard Graphics 
3 Underline 
2 Reverse Video 
l Blinking 
0 (low order) Overline 


Color Bits 


The color bits (green, red, blue) have different effects on color 
and monochrome displays. For color displays, they each con- 
trol the output of one of the display’s three color guns. For 
monochrome displays, the color bits can be used in various 
combinations to control display intensity. Table G-3 lists the 
combination of color bits effects for color and monochrome 
display types. 


Table G-3 Color Bit Combinations 


Green | Red | Blue | Color Monochrome 





























0 0 0 Black Secret (no display) 
0 0 l Blue Most dim 

0 l 0 Red 

0 l l Magenta 

l 0 0 Green 

l 0 l Cyan 

l l 0 Yellow 

l l l White Brightest 
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VRAM CRT Display 


Standard Graphics Characters 


The APC III hardware supports a standard graphics character 
feature that allows the hardware to map a display character 
position matrix (8 x 16 pixels) into an array of eight (4 « 4 pixel) 
tiles. Each of the eight tiles are controlled by a corresponding 
bit in the display character. To use this feature, a register called 
“Mode Flip-Flop” must be used to switch the meaning of the 
Vertical Strike-Through/ Standard Graphics attribute bit. The 
ROM BIOS display modes always set the Mode Flip-Flop to 
use this bit as vertical Strike-Through. If use of the Standard 
Graphics Character feature is required, refer to the A PC /// 
System Reference Guide for more information. 


Graphics VRAM Memory Map 


The standard APC III is equipped with 64 KB of graphics 
VRAM. The ROM BIOS includes support for this memory as 
two pages of a plane of pixels up to 640 = 400 pixel resolution. 
To achieve color graphics, the APC III Color Graphics option 
adds memory to a total graphics memory size of 192 KB. This 
is enough to support two pages of three color planes of up to 
640 = 400 pixel resolution. In color modes, the color of a pixel 
on the display screen is controlled by combining the bits for 
that pixel position from the three color planes (normally green, 
red, and blue). 


There are two pages (screens) of memory supported by ROM 
BIOS for every graphics display mode. Additional pages, for 
lower resolution modes, are allowed by the hardware and may 
be configured for the software which bypasses the ROM 
BIOS. A bank switching scheme 1s used to select the page of the 
memory to be used for any operation. Also provided 1s inde- 
pendent control of the page currently accessible by the MPU, 
in the MPU’s memory address space. The ROM BIOS Select 
Active Page call always selects both of these aspects together. 
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VRAM CRT Display 


The correspondence between the three regions of display 
memory (color planes designated as PI, P2, and P3) and the 
actual colors that are displayed is controlled by a palette 
register. The register allows any three-bit input combination to 
be mapped into a specific combination of the three colors to be 
displayed. The palette registers can be thought of as an eight- 
element array (indexed [0..7]) by the three-bit output of the 
memory color planes. Each element of the array contains a 
three-bit number that specifies the colors that are sent to the 
CRT hardware for a corresponding 3-bit input combination. 


Note For monochrome displays, the previous discussion 
is valid, but the colors are displayed as varying 
shades of grey intensity. 


Input — Palette Registers ~ Output 
fromcolor planes (8 3-bit registers) to CRT color guns 
3 bits: Pl, Pz. P3 3 bits (R, G, B) 


During normal use (including modes set up by ROM BIOS), 
the palette registers are programmed to make the three color 
planes behave in the most natural manner; that is, green, red, 
and blue planes, respectively, as shown in Table G-4. 
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VRAM CRT Display 


Table G-4 Palette Registers Input and Output 


Input Palette | Register GEB Color 
(P1, P2, P3) | Index | Contents 


black (none) 
blue 

red 

magenta 
green 

cyan 

yellow 

white 
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Note For monochrome displays, blue is the dimmest 
shade, and white is the brightest. 


You can alter the palette register using the ROM BIOS calls by 
modifying the mapping. Table G-5 lists a modified version of 
Table G-4. The mappings for cyan and magenta have been 
modified to produce yellow. 


Table G-5 Modified Palette Registers Input and Output 


Input Palette | Register aes Color 
‘ig # P?, P3) | Index | Contents 


black (none) 
blue 

red 

yellow 

green 

yellow 
yellow 

white 
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The remapping can be achieved by simply altering the contents 
of palette registers 3 and 5. 
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VRAM CRT Display 


The APC III can be equipped with | (standard) and 3 (color 
graphics option) planes of graphics display memory. It 1s 
sufficient for images of up to 640 < 400 and eight different 
colors (including black). Each plane consists of 64 KB of 
memory. Each bit inthe memory corresponds to a single pixel 
on the screen. Table G-6 summarizes the use of graphics on the 
APC III for the modes available through ROM BIOS. This is 
not a comprehensive list of the possible modes. For a more 
detailed list of the graphics display hardware, refer tothe A PC 
ITI System Reference Guide. 


Table G-6 Available Graphic Modes on the APC III 


MPU Address ROM BIOS 
Start End Mode Modes 


A800:0000-A800:7D00 | PI 640 = 400 
A800:0000-A800:3E80 | PI 640 = 200 
A800:0000-A800:3E80 | PI 320 x 200* 


~~) \O 


J 


B000:0000-B000:7D00 | P2 640 x 400 
B000:0000-B000:3E80 | P2 640 x 200 
B000:0000-B000:3E80 | P2 320 < 200* 
B800:0000-B800:7D00 | P3 640 x 400 
B800:0000-B800:3E80 | P3 640 x 200 
B800:0000-B800:3E80 | P3 320 x 200* 


hNOBRNORAD COC 





*The 320 x 200 graphics modes are accomplished in the ROM BIOS by 
actually selecting a 640 x 200 pixel mode and doubling the pixels in the 
horizontal direction as they are set. This will be transparent to programs 
that use the ROM BIOS calls that manipulate pixels. However, any pro- 
gram directly accessing the graphics VR AM in 320 x 200 modes will have to 
perform the doubling itself. For example, to set logical pixel (0,0) in 320 x 
200 mode, the program would need to set BOTH bit 7 and bit 6 at 
A800:0000. 


Within each plane and for every mode, the correspondence 
between bits of the VRAM memory and pixels are the same. 
The first raster line of pixels on the screen may come from the 
first 80 (decimal) bytes of the memory area. The second raster 
line will come from the next 80 bytes and so forth until the last 
(200th or 400th) line has been mapped. From each byte of 
memory, the high-order bit is displayed first. 
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Appendix H 
Keyboard Character Set 





This appendix gives a list of the APC III keyboard character 
set. Figures H-!l and H-2 shows the APC III keyboard layout 
and the keyboard scan codes/ key position conversion chart, 
respectively. In Figure H-1, the numbers appearing in the 
lower corner designate the key position. 


In Table H-| the numbers in parentheses are either ASCII or 
extended ASCII codes. An extended ASCII code would look 
similar to (00 XX). The codes that are not in parentheses are 
either graphic or mnemonic symbols associated with the 
ASCII code. Please note that certain key/shift state combina- 
tions which produce valid extended ASCII codes are not listed 
in Table H-1. These codes are produced for various keys in the 
available shift states and are listed in Table H-2. 


PF1 | PF2 | PF3 | PF4 PF6 PF7 | PF8 | PF9 |PF10|PF11/PF12 PgUp |PgDn 

62 63 64 65 67 68 69 70 71 72 73 74 75 
pat Break 
—- 80 









Back 
Space , 
Ctrl an a 
,{ Lock, 35 36 39 S48 


Grph Help 
2 57 60 











Figure H-1 APC III Keyboard Layout 


Table H-2 shows the extended keyboard character set. 
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Keyboard Character Set 
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Figure H-2 Keyboard Scan Codes/Key Position Conversion Chart 
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Table H-1 Keyboard Character Set 


Keys 


Key Scan Code 
Position | Unshifted | Shift Ctrl Grph 1 Grph 2 (hex) 


Base | Base Upper Base | Base Upper 


t-HS 


ESC 
(1B) 
No Code 

NUL 
(00 00) 
No Code 
No Code 
No Code 
No Code 
No Code 
No Code 


No Code 


No Code 
(00 50) 
(00 51) 
(00 52) 
(00 53) 
(00 54) 
(00 55) 
(00 56) 
(00 57) 


(00 58) 


No Code 


No Code 


No Code 


No Code 


No Code 


No Code 


No Code 


No Code 


No Code 


No Code 


No Code 


No Code 


No Code 


No Code 


No Code 


No Code 


No Code 


No Code 


No Code 


No Code 
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b-HS 


Table H-1 Keyboard Character Set (cont’d) 


Key Scan Code 
Position | Unshifted | Shift Ctrl Alt Grph 1 Grph 2 (hex) 
Base Upper | Base Upper 


No Code No Code 




















Jag dajovaDY) pavoqgkay 






No Code 











(00 59) 








US No Code No Code 





(1F) 
No Code 


(00 5A) 














No Code No Code 





(00 5B) 
No Code 





No Code No Code No Code 













DEL No Code No Code No Code 







(7F) 
No Code 
















No Code No Code No Code 






DCI 












(11) (80) (AO) | (CO) (EO) 


ETB 
(17) 
ENQ 
(05) 
DC2 


(00 10) 











(00 11) | (81) (Al) | (Cl) (EI) 












(00 12) | (82) (A2) | (C2) (E2) 














(12) (00 13) | (83) (A3) (C3) (E3) 
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Table H-1 Keyboard Character Set (cont’d) 


Keys 


Key Scan Code 
Position | Unshifted | Shift Ctrl Alt Grph 1 Grph 2 (hex) 
Base Upper | Base Upper 


(74) (00 14)| (84) (A4) | (C4) (4) 
(79) (00 15)} (85) (AS) | (C5) (E5) 
(75) (00 16)} (86) (A6) | (C6) (E6) 


(69) (OO 17) | (87) (A7) (Cy) (ES) 


(6F) (00 18)} (88) (A8) | (C8) (E8) 


(70) (00 19)}| (89) (AQ) (C9) (E9) 
No Code 
(SB) (8A) (AA) | (CA) (EA) 
No Code 
(SD) (8B) (AB) | (CB) (EB) 
No Code 
(SC) (8C) (AC) | (CC) (EC) 
No Code No Code 
(8D) (AD) | (CD) (ED) 
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Table H-1 Keyboard Character Set (cont'd) 


Key Scan Code 
Position | Unshifted | Shift Ctrl Grph 1 Grph 2 (hex) 


No Code 


No Code 
A 

(41) 
S 

(53) 
D 

(44) 


(46) 
(47) 
(48) 
(4A) 


(4B) 


Keys 


No Code 


No Code 
(00 1E) 
(00 1F) 
(00 20) 
(00 21) 
(00 22) 
(00 23) 
(00 24) 


(00 25) 


Base | Base Upper | Base Upper 


No Code 


No Code 
(8E) (AE) 
(8F) (AF) 
(90) (BO) 
(91) (BI) 
(92) (B2) 
(93) (B3) 


(94) (B4) 


(95) (BS) 


Base | Base Upper 
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Table H-1 Keyboard Character Set (cont'd) 


Keys 


Key Scan Code 
Position | Unshifted | Shift Ctrl Grph 1 Grph 2 (hex) 


L-HS 


(6C) 

(3B) 

(27) 
CR 


(OD) 
No Code 


(7A) 
(78) 
(63) 
(76) 


(62) 


FF 

(OC) 
No Code 
No Code 
LF 


(OA) 
No Code 


(IA) 
(18) 
(03) 
(16) 


(02) 


(00 26) 
No Code 


No Code 


No Code 


No Code 


(00 2A) 
(00 2B) 
(00 2C) 
(00 2D) 


(00 2E) 


Base | Base Upper 
Raves (BO) 
(97) (B7) 
(98) (B8) 
No Code 


No Code 


(99) (B9) 
(QA) (BA) 
(9B) (BB) 
(9C) (BC) 


(9D) (BD) 


Base ) Base Upper 


(D6) eer 
(D7) (F7) 
(D8) (F8) 
No Code 


No Code 


(D9) (F9) 


(DA) (FA) 
(DB) (FB) 


(DC) (FC) 





(DD) (FD) 
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Table H-1 Keyboard Character Set (cont'd) 


Keys 


Key Scan Code 
Position | Unshifted | Shift Ctrl Grph 1 Grph 2 (hex) 


Base | Base Upper Base | Base Upper 


(6E) (4E) (OF) 


(00 2F) horas (BE) 


(DE) feeekised 


8-HS 


(6D) 


(2C) 


(2E) 


(2F) 
No Code 


No Code 
SP 

(20) 
No Code 


HELP 
(00 6F) 


(4D) 


(3C) 


(3E) 
: 

oP} 
No Code 


No Code 
SP 

(20) 
No Code 


No Code 


CR 
(OD) 
No Code 


No Code 
No Code 
No Code 
No Code 
SP 


(20) 
No Code 


(00 BB) 


(00 30) 
No Code 


No Code 
No Code 
No Code 
No Code 
SP 


(20) 
No Code 


(00 CB) 


(9F) (BF) 


No Code 


No Code 


No Code 


No Code 


No Code 


No Code 


No Code 


No Code 


(DF) (FF) 


No Code - 


No Code 


No Code 


No Code 


No Code 


No Code 


No Code 


No Code 





1aG 4ajavADYD pavoqday 


Table H-1 Keyboard Character Set (cont’d) 


Keys 


Key Scan Code 
Position | Unshifted | Shift Ctrl Grph 1 Grph 2 (hex) 


| Base Upper | Base Upper | Base Upper Base | Base Upper 


6-HS 


No Code 


(00 62) 
(00 63) 
(00 64) 
(00 65) 
(00 66) 
(00 67) 
(00 68) 
(00 69) 


(00 6A) 


No Code 


(00 8C) 


(00 8D) 


(00 8E) 


(00 8F) 
(00 90) 
(00 91) 
(00 92) 
(00 93) 


(00 94) 


No Code 


(00 98) 
(00 99) 
(00 9A) 
(00 9B) 
(00 9C) 
(00 9D) 
(00 9E) 
(00 9F) 


(00 AO) 


No Code 


(00 A4) 
(00 AS) 
(00 A6) 
(00 A7) 
(00 A8) 
(00 A9) 
(00 AA) 
(00 AB) 


(00 AC) 


No Code 


No Code 


No Code 


No Code 


No Code 


No Code 


No Code 


No Code 


No Code 


No Code 


No Code 


No Code 


No Code 


No Code 


No Code 


No Code 


No Code 


No Code 


No Code 


No Code 
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Table H-1 Keyboard Character Set (cont'd) 


Position | Unshifted | Shift Ctrl Grph I Grph 2 (hex) 


| Base Upper | | Base Upper | | Base Upper | | Base Upper | 


OI-HS 


(00 6B) 
(00 6C) 
(00 6D) 


Page Up 


(00 35) 


Page 
Down 

(00 36) 
Ins 

(00 37) 


(2F) 
Home 
(00 3D) 
Print 
(00 61) 


(00 95) 
(00 96) 
(00 97) 


Page Up 


(00 35) 


Page 
Down 

(00 36) 
Ins 

(00 37) 


(2F) 
Home 
(00 3D) 
Hrd Copy 
(00 60) 


(00 Al) 
(00 A2) 
(00 A3) 


Top of 
Text and 
Home 

(00 BO) 


Erase to 
EOS 
(00 Bl) 


(00 B2) 
No Code 


Clr Scrn 
(00 B8) 
Echo 
(00 BA) 


(00 AD) 
(00 AE) 


(00 AF) 


(00 CO) 


(00 C1) 


(O00 C2) 
No Code 


(00 C8) 


(00 CA) 


No Code 


No Code 


No Code 


No Code 


No Code 


No Code 


No Code 


No Code 


No Code 


No Code 


No Code 


No Code 


No Code 


No Code 


No Code 


No Code 


No Code 


No Code 
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Table H-1 Keyboard Character Set (cont'd) 


Keys 


Key Scan Code 
Position | Unshifted | Shift Ctrl Alt Grph 1 Grph 2 (hex) 


Base Upper Base Upper 


IT-HS 


Break 
(00 60) 


DEL 
(00 38) 


(2A) 
(37) 

(38) 

(39) 

(2D) 

(00 39) 
(34) 


(35) 


Break 
No Code 
DEL 

(00 38) 


(2A) 
(37) 

(38) 

(39) 

(2D) 

(00 39) 
(34) 


(35) 


Break 
Process 


(00 B3) 
No Code 


No Code 
No Code 
No Code 
No Code 

(00 B4) 
No Code 


No Code 


(00 C9) 


(00 C3) 
No Code 


No Code 
No Code 
No Code 


No Code 


(00 C4) 
No Code 


No Code 


No Code 


No Code 


No Code 


No Code 


No Code 


No Code 


No Code 


No Code 


No Code 


No Code 


No Code 


No Code 


No Code 


No Code 


No Code 


No Code 


No Code 


No Code 


No Code 


No Code 
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Table H-1 Keyboard Character Set (cont’d) 
Keys 


Key 
5 d 


Base Upper | Base Upper 


CI-HS 


No Code 


No Code 
Rev. Wrd 

(00 BS) 
Adv. Wrd 

(00 B6) 
No Code 
No Code 
No Code 


LF 


(OA) 


(00 B7) 
No Code 


No Code 


No Code 


No Code 


(00 CS) 


(00 C6) 
No Code 


No Code 
No Code 
No Code 

(00 C7) 
No Code 


No Code 


No Code 


No Code 


No Code 


No Code 


No Code 


No Code 


No Code 


No Code 


No Code 


No Code 


No Code 


No Code 
No Code 
No Code 
No Code 
No Code 
No Code 
No Code 
No Code 
No Code 
No Code 


No Code 
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Keyboard Character Set 


Table H-2 Extended Keyboard Character Set 


Second Code } Function 
(Hex) 


NUL Character Note By default, the MS-DOS 
keyboard device driver will 
not return these codes, 
unless they have been 
remapped with the Re-map 
Key Code Escape sequence. 


OW, EBT, ¥,0;,4,0,P 

fie Oe Li. Py Ue My ale Bee 

Z, X, C, V, B, N, M 
Pg Up 
Pg Dn 
Ins 
Del 
2544 
Clear Home 
Alt 1, 2, 3, 4, 5, 6, 7, 8, 9, 0, -, =, (Key 2 - 13) 
Break Stop 
Print 
PF1-PF12 (Unshifted Function Keys) 
Help 
PFi-PF2 (Fae; PF1 = PF12) 
PF1-PF12 (Shift, PFl - PF12) 
PF]-PFI2 (Ctrl, PFl - PFI2) 
PPi=PPI2Z {Ali PF1l=PFI2) 
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Table H-2 Extended Keyboard Character Set (cont’d) 


Second Code | Function 
(Hex) 


Ctrl, Pg Up 
Ctrl, Pg Dn 
Ctrl, Ins 

Ctrl, Del 

Ctrl, f 

Ctrl, — 

Ctrl, — 

Ctr. 4 

Ctrl, Clear Home 
Ctrl, Print (Start/Stop Echo to Printer) 
Ctrl, Help 

Alt, Pg Up 

Alt, Pg Dn 

Alt, Ins 

Alt, Del 

Alt, t 

Alt, = 

Alt, > 

Alt, | 

Alt, Clear Home 
Alt, Break Stop 
Alt, Print 

Alt, Help 
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Table H-2 Extended Keyboard Character Set (cont'd) 


Second Code | Function 
(Hex) 


, Clear Home 
, Break Stop 
, Print 

Help 
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Keyboard Character Set 
Table H-3 outlines the guidelines for key usage when performing com- 
monly used functions. 


Table H-3 Suggested Keyboard Functions 


Home cursor Editors, word processing 


Return to outermost Menu-driven applications 
menu 


Move cursor up Full screen editor, word 
processing 


Page up, scroll Editors, word processing, 
backwards 25 lines, and 
home 

Move cursor left Text command entry 


Move cursor right Text command entry 


Move cursor down Full screen editor, word 
processing 


Page down, scroll Editors, word processing, 
forwards 25 lines, and 
home 


Start/Stop insert text at | Text command entry 
cursor. Shift text right in 
buffer. 


Del Delete character at cursor| Text command entry 


Back Space Destructive back space Text command entry 


Tab — Tab forward Text entry 
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Table H-3 Suggested Keyboard Functions (cont’d) 


Tab — 


Ctrl, 
Clear Home 


Esc 
Ctrl — 
Ctrl — 


Break Stop 


Ctrl, Break Stop 


Fne, Cir, 
Break Stop 


Ctrl, Pg Up 


PFI-PF12 

Poe, Shift, Ctrl, 
or Alt, 
PFI-PF12 

Alt 2-13 


Alt A-Z 


Tab backward 


Clear screen and home 


Exit/escape 
Advance word 
Reverse word 


Suspend system (pause) 


Break Interrupt 


System Reset 


Top of document and 
home cursor 


Standard function keys 


Secondary function keys 


Extra function keys 


Extra function keys 
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Text entry 


Command entry 


Editor, | level of menu 
Text entry 
Text entry 


Stop list, stop program, 
etc. Resumes on any key. 


Interrupts current process 


Reboots the system 


Editors, word processing 


Primary function keys 


Extra function keys 


Used when function starts 
with same letter as one of 


| the alpha keys. 





Appendix I 


APC III Hard Disk 
Information 





This appendix provides technical information regarding the 
APC III hard disk options. Information on setting up and 
Operating the hard disk under MS-DOS is presented in the 
APC III Supplement to the MS- DOS User’s Guide. A detailed 
description of the hard disk controller may be found in the 
APC III System Reference Guide. 


In order to provide the flexibility of logically segmenting the 
hard disk storage area for different operating systems, users, 
and specialized storage requirements, NEC has implemented a 
partitioning scheme that is outlined in this appendix. The 
master hard disk boot record (stored in the first sector of the 
hard disk) and the Hard Disk Partition Table (stored in the 
second sector of the hard disk) provide the means of accessing 
any partition easily. 


Hard Disk Partition Table 


The Hard Disk Partition Table, described in Table I-1, con- 
tains all information concerning the hard disk partitions. It 
resides on the second sector of track 0. Under MS-DOS, this 
table is created (for an uninitialized hard disk) and maintained 
by the HDSETUP utility. 
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Table I-1 The Hard Disk Partition Table 


1 byte Number of partitions 


1 byte Current hard disk boot parti- 
tion number 


30 bytes Reserved 
32 bytes Partition #| parameter block 
32 bytes Partition #2 parameter block 


32 bytes Partition #12 parameter block 
92 bytes Reserved 


2 bytes Reserved (must = 0 for this 
release of MS-DOS) 


2 bytes ID (must = 55AAH) 





The ID bytes must be present to signify a valid partition table. 
They also appear at the same offset in the master hard disk 
boot record and in the boot record of all MS-DOS partitions. 
If these values do not appear when expected, the record 1s 
considered invalid. 


Each 32-byte partition parameter block consists of the follow- 


ing: 

1 byte — Active partition indicator (1 = active, 
0 = not) 

1 byte — Operating system indicator (1 = MS-DOS) 

2 bytes — Reserved 

1 Dword — Location of initial program loader (sector 
number) 

| Dword — Partition start sector number 

1 Dword — Partition end sector number 

10 bytes — Partition name 

6 bytes — Reserved 
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The double word sector numbers indicating the partition start, 
end, and IPL location are given relative to the very beginning 
of the hard disk, starting at sector 0. For example, if partition 
#1 begins on sector 34, the partition begins on sector 35 of the 
hard disk. This sector will become “relative” sector 0 within the 
partition itself. 


MS-DOS Partition Format 


Hard disks are formatted with 17 sectors (512 bytes per sector) 
per track. Partitions must be allocated on track boundaries, 
with the first 2 tracks of the hard disk reserved. File allocation 
unit size depends on the size of the partition. If the partition 1s 
620 tracks or less (up to 5 megabytes), it will be formatted with 
4 sectors per allocation unit (2048 bytes). If the partition 1s 
between 621 and 1240 tracks (up to 10 megabytes), it will be 
formatted with 8 sectors per allocation unit (4096 bytes). The 
first sector of the partition is reserved for the initial program 
loader, after which two FATs are allocated with a length of 8 
sectors each. The root directory can have up to 272 entries. 


System Initialization 


Following a power-on or reset, MS-DOS is booted and initial- 
ized in the following way. 


|. The battery backed non-volatile memory is read for the 
system boot drive indicator. If this value designates a 
hard disk drive as the boot drive, the master hard disk 
boot record (located on sector 0) of that drive is read. 


2. The master hard disk boot record contains code which 
reads the Hard Disk Partition Table. The second byte of 
the partition table contains the number of the boot parti- 
tion. This value is set either by the BOOT utility or by 
selecting a boot volume by holding down the correspond- 
ing PF key at boot time. (The hard disk boot process is 
described in the APC I/I Supplement to the MS-DOS 
User’s Guide.) 
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3. If no partition has been designated or no PF key was 
held, the system will attempt to boot from a diskette 
drive. This cycle will continue until a system diskette is 
placed in the diskette drive or the system is powered 
down. 


4. Ifthe Hard Disk Partition Table has a designated boot 
partition, the code from the master hard disk boot record 
will then read the parameter block of that partition for 
two important indicators. First, it will confirm that it is 
an active partition. 


5. Second, it will read the sector containing the initial pro- 
gram loader in that partition. If the ID bytes (SSAAH) 
are found at the end of the IPL sector, then program 
control is given to the IPL. 


6. The IPL will search the directory of the partition for the 
system files named IO.SYS and MSDOS.SYS and then 
begin loading them. 


7. Ifthe system files do not exist, the system will try to boot 
from a diskette drive. It is necessary to use a system 
diskette in drive A: or B: if the active hard disk partition 
has not been formatted with the /S option. 
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Sample Hard Disk 


Table I-2 outlines the contents of a sample hard disk by sector 


number. 


Table I-2 Sample Hard Disk 


Sector Number 


Sector 0 


Sector | 


Sector 27 FAH 


Sector 27 FBH 
Through 280BH 


Sector 2800CH 





Contents 


Master hard disk boot record 
Hard Disk Partition Table 
Offset Value Description 


+00H 04 Number of partitions. 


+01H Boot volume is partition 
02 #2. 


+40H 01 First byte of partition #2 
parameter block; it 1s 


active. 
+44H 27FAH Location of IPL. 


IPL code 
FATs for partition #2 


Root Directory with IO.SYS and 
MSDOS.SYS 
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Appendix J 


GRAPH Installable Driver 
(GRAPHIC.SYS) 





The GRAPH Installable driver, written by NEC, provides a 
universal and easy-to-use method of accessing the vast graphic 
capabilities of the APC III. The driver consists of a character 
output interface that may be used by most MS-DOS 2.11 
programming languages, utilities, and applications that are 
capable of sending output to a character oriented device. 


This appendix describes the installation of the driver and the 
purpose and syntax of its commands and operations. It also 
includes a sample M-BASIC program to demonstrate the use 
of the driver. 


Applications 


In many cases, a user or programmer finds it necessary to write 
a specialized and non-generic program that interfaces an 
application or utility to the graphics hardware of the APC III. 
GSX does not provide an easy-to-understand interface to 
graphics hardware. The GRAPH Installable driver provides a 
character oriented interface that is easy to use and understand. 
Only a limited vocabulary of commands need to be learned in 
order to take advantage of the APC III graphics hardware. 
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How to Use the GRAPH Installable Driver 


The following steps describe how to install the GRAPH Instal- 
lable driver on your system so it is available for use. 


bs 


Create or modify the CONFIG.SYS file, which is located 
in the root directory of the diskette or hard disk volume 
to be booted, to include the following line of text. 


DEVICE = GRAPHIC SYS <<r> 


Copy the GRAPHIC.SYS file into the root directory of 
the bootable disk volume or system diskette. 


Reboot the APC III via the <Fne> + <Ctrl>+ <Break / 
Stop> key sequence, RESET switch, or powering on. Be 
sure to boot from the system diskette or hard disk volume 
that contains the CONFIG.SYS and GRAPHIC.SYS 
files. 


Use the GRAPH Installable driver as a character I/O 
device with the name of “GRAPH”. 


Refer to the section on Operation and Command Descriptions 
foracomplete list of the capabilities for the “GRAPH” device. 


Syntax and Data Conventions 


The following notes apply to the syntax and use of the GRA- 
PHIC.SYS installable driver. Read these notes carefully to 
understand the general syntax of the driver’s commands. 


1. 


The bracket characters ([ and ]) enclose optional parame- 
ters. The angle bracket characters (<< and >) enclose 
required parameters. The underscore character (_) 
denotes that a space is required to separate the option and 
the attribute fields of a parameter. 


The comma and semicolon characters (, and ;) are signifl- 
cant and must be used within the syntax. 


The vertical bar character (|) indicates an exclusive OR. 


The values for xl and x2 must be in the range of 0-639. A 
command that exceeds this range is ignored and the 
program continues. 
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The values for yl and y2 must be in the range of 0-399. A 
command that exceeds this range is ignored and the 
program continues. 


The values for radius should only be in the range 0-199. 
Although the radius can be specified within a range of 
0-319, values larger than 199 can result in memory area 
overwrites in adjacent color planes. 


When specifying the arc begin and arc end values for 
ARC drawing, the following rules apply. 


@ When it is desirable to draw arcs that start at angles 
less than 360 degrees and extend beyond 360 degrees, 
then the ending angle must have a value within the 
range of 360-720 degrees. 


@ Angle values are in increments of | degree; they must 
be integer values. 


RECT, MOVE, COPY, and ERASE operations must 
have the xl and yl values specified as the upper left 
corner and the x2 and y2 values as the lower right corner 
for the rectangle to be drawn. The x3 and y3 values for the 
COPY and MOVE operations define the new upper left 
corner for the specified block’s destination. 


The x1 and yl values for CIR and ARC drawing are used 
as the center. 


MOUSE and JOYSTICK are mutually exclusive selec- 
tions but may be changed dynamically. 


The color option<cnum> forthe FILL action represents 
the current border color for the area to be filled. Any 
color that is not equal to the specified border color will be 
overdrawn in the area to be filled. Attempting to fill an 
area that has no discernable borders will cause the fill to 
escape to other areas on the screen. Borders are very 
important to the filling process, and areas for polygons 
(including circles, rectangles, etc.) must have solid borders 
(line style 0 or 7) to ensure a proper fill operation. 


Text strings are limited to 80 characters each. Text strings 
exceeding 80 characters will be truncated after the 80th 
character. 


The x! and yl values for the TEXT action specify the 
upper left corner of the first character’s 8 x 16 or 8 x 8 
block. 
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14. 


In order to read the MOUSE or SOYSTICKs, a program 
or utility must simply perform a read operation from the 
GRAPH device. The following describes the structure of 
the data that is returned upon the read request. 


Structure of MOUSE Data 


Current X coordinate of 000-639 in ASCII decimal 
followed by either a space or a comma (refer to the 
SET operation for more detail). Three characters / dig- 
its are always returned with leading zeroes. 


Current Y coordinate of 000-399 in ASCII decimal 
followed by either a space or a comma (refer to the 
SET operation for more detail). Three characters / dig- 
its are always returned with leading zeroes. 


The most recent switch code in ASCII decimal as 
follows: 


0 = No switch pressed 

| = Switch | pressed (left) 

2 = Switch 2 pressed (middle) 
4 = Switch 3 pressed (right) 


Terminator code of <cr> ends the sequence. 


Structure of JOYSTICK Data 


Current X coordinate of 000-639 for JOYSTICK Ain 
ASCII decimal followed by either a space or acomma 
(refer to the SET operation for more detail). Three 
characters/digits are always returned with leading 
zeroes. 


Current Y coordinate of 000-399 for JOYSTICK Ain 
ASCII decimal followed by either a space ora comma 
(refer to the SET operation for more detail). Three 
characters/digits are always returned with leading 
zeroes. 


Current X coordinate of 000-639 for JOYSTICK Bin 
ASCII decimal followed by either a space or acomma 
(refer to the SET operation for more detail). Three 
characters/digits are always returned with leading 
zeroes. 


Current Y coordinate of 000-399 for JOYSTICK Bin 
ASCli decimal followed by either a space or acomma 
(refer to the SET operation for more detail). Three 
characters/digits are always returned with leading 
Zeros. 
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@ The most recent switch code in ASCII decimal as 
follows: 


0 = No switch pressed 

| = Switch | pressed for JOYSTICK A 
2 = Switch 2 pressed for JOYSTICK A 
4 = Switch | pressed for JOYSTICK B 
8 = Switch 2 pressed for JOYSTICK B 


@ Terminator code of <cr> ends the sequence. 


15. The INIT operation sets the coordinate values to the 
upper left (000,000) position of the display screen and the 
switch code to 0 for MOUSE. JOYSTICK coordinates 
are set to 320,200 and the switch codes are set to 0. 


16. All optional parameters, when specified, supersede the 
corresponding default parameters set by the SET com- 
mand. 


Operation and Command Descriptions 


This section describes the syntax and purpose of the opera- 
tions and commands provided by the GRAPH Installable 
driver. 


ARC,<x1l>,<yl>,<radius>,<are begin>,<arc end>, 
<cnum>,[<line style>],[<screen spec>]<cr> 


Draws an arc with a center at the coordinates specified by 
<x1> and <yl> having a radius specified by <radius>. The 
angle that is subtended by the arc is specified by the <arc 
begin> and <arc end> parameters (refer to Syntax and Data 
Conventions, Note 7, for more details). The color of the border 
line is specified by the <cnum> parameter. The border line 
will be drawn with the line style specified by the current default 
value set by the SET command or the optional <line style> 
parameter. The circle will be drawn in the default screen set by 
the SET command or in the screen specified by the optional 
<screen spec> parameter. 
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CIR,<x1l>,<yl>,<radius>,<cnum>,[<line style>], 
[<screen spec>]<cr> 


Draws a circle with a center at the coordinates specified by 
<x1> and <yl> having a radius specified by <radius>. The 
color of the border line is specified by the <cnum> parameter. 
The border line will be drawn with the line style specified by the 
current default value set by the SET command or the optional 
<line style> parameter. The circle will be drawn in the default 
screen set by the SET command or in the screen specified by 
the optional <screen spec> parameter. 


CLEAR<cr> 


Clears the entire default screen specified by the SET command. 


LOPY «xl yl Sa ee 


Copies the area enclosed by the rectangle defined by the coor- 
dinates specified by the <x1>, <yl>, <x2>, <y2> parame- 
ters to an equal-sized rectangular area with its upper left corner 
specified by the <x3> and <y3> parameters. The upper left 
corner for the area to be moved is defined by the <x1> and 
<y1l> parameters. No orientation changes are performed dur- 
ing the copy operation. 


CURSOR,<ON |OFF><cr> 


Activates and deactivates the display of cursors that follow the 
movement of the MOUSE and JOYSTICKs. The cursor color 
for JOYSTICKs A and Bare red and green respectively. The 
cursor color for MOUSE 1s white. 


EKASE.<x Lay lk 2 


Fills the area that is enclosed by the rectangle defined by the 
<xl>, <yl>, <x2> and <y2> parameters with the color 0 
(black). 


FILL, ,<xl><yl>.<cnum>,<iill spec ><cr> 


Fills an area bounded by a color specified by the <cnum> 
parameter. The new color and pattern are specified by the <fill 
spec> parameter. The starting coordinate for the fill opera- 
tion, commonly called the “seed,” is specified by the <x 1>and 
<yl> parameters. 
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INI T<cr> 


The INIT command must be executed once before any other 
commands may be sent to the GRAPH device. The INIT 
command presets the following conditions. 


Mode = color or monochrome determined 
by system hardware 
Resolution = 640 x 400 


Display screen = 0 
Drawing screen = 0 
Cursor addresses and switch codes are set to logical zero. 


(Refer to Syntax and Data Conventions, Note 15, for more 
details.) 


Palette registers are initialized as follows. 


Register 
Number Value 





SAN BRWN— © 
NAMB WN— © 
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JOYSTICK,<ON | OFF><cr> 


Activates the JOYSTICKs interface and mutually excludes the 
use of the MOUSE. 


LINE,<x1l>,<y1l>,<x2>,<y2>,<cnum>,[<line style>], 
[<screen spec>]<cr> 


Draws a line between the coordinates specified by the <xI>, 
<yl> and <x2>, <y2> parameters. The color of the line 1s 
specified by the <cnum> parameter. The line will be drawn 
with the line style specified by the current default value set by 
the SET command or the optional <line style> parameter. 
The line will be drawn in the default screen set by the SET 
command or in the screen specified by the optional <screen 
spec> parameter. 


MOUSE,<ON | OFF><cr> 


Activates and selects the type of MOUSE to be used on the 
standard serial port (AUX) of the APC III. This command 
also mutually excludes the use of the JOYSTICKs. 


MOV Box Sy Lx 2 SSS er 


Copies the area enclosed by the rectangle defined by the coor- 
dinates specified by the <x1>, <yl>, <x2>, <y2> parame- 
ters to an equal-sized rectangular area with its upper left corner 
specified by the <x3> and <y3> parameters. The upper left 
corner for the area to be moved is defined by the <x1> and 
<y1> parameters. No orientation changes are performed dur- 
ing the copy operation. After the copy is performed, then the 
area that is enclosed by the rectangle defined by the <xI>, 
<yl>,<x2> and <y2> parameters will be filled with the color 
0 (black). 


RECT <xl><yl2>,.<52>><y2>,<cnum>,|<line style>|. 
[<screen spec>]<cr> 


Draws a rectangle with a height of <x2> minus <xl> anda 
width of <y2> minus <yI> starting at the upper left corner 
specified by the <x1>and <yIl> parameters. The color of the 
border line is specified by the <cnum> parameter. The border 
line will be drawn with the line style specified by the current 
default value set by the SET command or the optional <line 
style> parameter. The rectangle will be drawn in the default 
screen set by the SET command or in the screen specified by 
the optional <screen spec> parameter. 
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SET,<<line style>|<screen spec>|<font spec> 
|<pallette spec>|<mouse spec>|<sep spec>><cr> 


Changes the value of the default parameters for the GRAPH 
device. (Refer to the Parameter Syntax Specifications for 
more detail.) 


TEXT,<x1l>,<yl>,<cnum>,<text string>,[<font spec>], 
[<screen spec>]<cr> 


Draws up to 80 characters of text in the default font style 
specified by the SET command or in the font style specified by 
the optional <font spec> parameter. The text will be drawn 
Starting at the coordinates specified by the <x1> and <yl> 
parameters. The starting coordinate defines the upper left 
corner of the first character’s 8 x 16 or 8 x 8 block. The color of 
the text is specified by the <cnum> parameter. The text will be 
drawn in the default screen set by the SET command or in the 
screen specified by the optional <screen spec> parameter. 


Parameter Syntax Specifications 


line style = LINE_<number range> 
0 = RK KK KK KOK OK KK invisible 2 2 2k 2k 2k 2k 2 2k 2k 2 2K 2k ok OK OK 
-—- * * * * * *K KK KOK KK OK K KK KK K 
2 — ** 2 2 2 2 * 2 K * * * * * 


3 — **KK KKK KKK KKK KKK KKK KKK KKK 

4 = **** 2 2k 2 2K 2K Ok 2k 3K OK 2 KK 

5 = KKK KK KK 3 2k 2 2K 2 3K Ok 2K 2K 2k 2 2k 2 2 
6 — KKK 2K 2 2K 2k 2 2K 2K Ok Kk 2K 2K OK ke OK 2K 2k OK OK KK 
1= OK 2 fe 2 ic ie fe fe ok 2 2 ie ic ae ie 2 ie ie oe ie fe fe ic 2k fe ie 2 oe ie ie 2c oe 2 2 2k 2K 2k 2 


Line style 0 is solid but invisible. 
text string = <alpha | digit>[<alpha | digit>]... 
fill spec = FILL_<cnum>;<pnum> 
screen spec = SCREEN_<0O|1> 


font spec = FONT_<0|1> 


0 =8 x 16 font (normal APC ITI) 
1=8x8 font (reduced APC III) 


pallette spec = PALLETTE_<number sequence> 
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mouse spec = MOUSE_<0|1> 
0 = Mouse Systems Mouse 
1 = SummaGraphics Mouse 
sep spec = SEP_<]_> 


The separator specification determines whether a comma 
Or a Space is inserted between groups of digits returned 
from the MOUSE or JOYSTICK. 





cnum = <number range> 


0 = black 

| = green 

2 = red 

3 = yellow 

4 = blue 

5 = cyan 

6 = magenta 
7 = white 


pattern = PATTERN_<number range> 
0 = half intensity 
1 = solid fill 
2 = vertical lines 
3 = horizontal lines 
4 = -45 degree diagonals 
5 = +45 degree diagonals 
6 = “X” crosshatch 
7 = right-angle crosshatch 


See Figure J-1 for pattern illustration. 


pnum = <number range> 


Use numbers corresponding to the same patterns as shown 
for the pattern parameter. 


number 

sequence = <<number range>;<number range>;<number range>; 
<number range>;<number range>;<number range>; 
<number range>;<number range>> 


number range = <0|1|2|3|4|5|6|7> 
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alpha=<A|B|C|D|E|F/G|/H|I|/J|K|L| 
M|IN|O/|P|Q|R|S|T|U|V|W/X| 























YI Zi 3 Ta Pete] Se) is 
Le PP ee leo | 
PLS (Mol Cel * | CL yl=| fal 


ejdielfitg/|hli|j lk] i i[m] al 
Cl ppg) thse me wee oe ee 


digit = <0|1/2|3|4|5|6|7|8|9> 





0 = 4= 

half —45 degree 

intensity diagonal 

1 = 5 = 

solid +45 degree 

fill diagonal 

2 = 6 — ate 
vertical “x” crosshatch ote 
lines <°. 
3= —————— /= 

ho21ad  ——————— right-angle 

lines Pe crosshatch 





Figure J-1 Available Patterns 
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Sample Program 


The program listing shown in Figure J-21s asimple M-BASIC 
program that produces output that is directed to the GRAPH 
device. The output from the program, shown in Figure J-3, 


produces the graphics output shown in Figure J-4. 


Although the program directs its output to the GRAPH 
device, the output could be directed to a regular disk file 
instead of the GRAPH device, and then the disk file or an 
edited version could be copied to the GRAPH device (COPY 
file to GRAPH). 


OPEN "'0'"',#1,''GRAPH' 
PRINT CHRE(27)7.°C2I"s 
PRINT #1,"1INIT" 

PRINT #1, "CLEAR" 
X1=0:Y1=0: Y2=200 

FOR X2=9 TO 639 STEP 70 
C=(C+1) AND 7 


PRINT iY RECT" sxiet erie" oK ee" 
NEXT X2 
FOR R=0 TO 199 STEP 40 


C=(C+1) AND 7 

PRINT #1, "°C1R,320,200,"3R3", "30 
NEXT RF 

FOR R=Q TO 200 STEP 40 

C=(C+1) AND 7 

PRINT #1, °ARC,0,0,"3R3°.270,360, °; 
PRINT #1, "ARC,639,0,"°3R3",180,270, 
NEXT R 

FUR ¥YIT=0O 10 399 STEP 40 


C= (C+1) AND 7 


PRINT #14 “LINE.O, "F¥1$",320, 200, "5 
PRINT #1, "LINE ,639,°5Y13",320,200, 


NEXT Y1 
CLOSE 
END 


ge ee ag 


C 


it eS 
LL 


Gs 
ana ® 


Figure J-2 Sample M-BASIC Program for Using 


the GRAPH Device 
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INIT 

CLEAR 

REET, O 4% Os Fa 200 5 i 
RECTs O » O « 79 5 200 4 2 
RECT; O » O 4 147 5 200 4 3 
RECT, O , © . 2197 ¢ 200 , 4 
RECT, O 4 O 5 2B? « 200 , 9d 
RECT, O » 0 4 SS? + 200 4 & 
RECT: O » O » 427 5 200 4 7 
RECT, O , © » 499 , 200 , 0 
RECT, O « O 5 S67 » ZOO , { 
RECT; O , O , 637 . 200 4 Z 


CIR,320,200, 0, 3 
CIR,320,200, 40 , 4 
CIR,320,200, 80 , 5 
CIR,320,200, 120 , 6 
CIR,320,200, 160 , 7 
ARC,0,0, O ,270,360, O 
ARC,639,0, O ,180,270, 0 
ARC,0,0, 40 ,270,360, 1 
ARC,639,0, 40 ,180,270, 1 
ARC .0,0, 80 ,270,360, 2 
ARC,639,0, 80 ,180,270, 2 
ARC,0,0, 120 ,270,360, 3 
ARC, 639,0, 120 «160,270; 3 
ARC,0,0, 160 ,270,360, 4 
ARC,639,0, 160 ,180,270, 4 
ARC,0,0, 200 ,270,360, 5 
ARC,639,0, 200 ,180,270, 5 
LINE,O, O ,320,200, 6 
LINE,639, O ,320,200, 6 
LINE,O, 40 ,320,200, 7 
LINE,639, 40 ,320,200, 7? 
LINE,O, 80 ,320,200, 0 
LINE,639, 80 ,320,200, O 
LINE,.O, 120 ,320,200, ! 
LINE ,639, 120 ,320,200, 1 
LINE,O, 160 ,320,200, 2 
LINE,639, 160 ,320,200, 
LINE,O, 200 ,320,200, 3 
LINE,639, 200 ,320,200, 
LINE,O, 240 ,320,200, 4 
LINE,639, 240 ,320,200, 
LINE.O, 280 ,320,200, 5 
LINE,639, 280 ,320,200, 
LINE,O, 320 ,320,200, 6 
LINE ,639, 320 5,320,200, 
LINE,O, 360 ,320,200, 7 
LINE .,639, 360 ,320,200, 7 


Oo YW F&F W DNDN 


Figure J-3 Output of M-BASIC Program 
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Figure J-4 Graphics Display from Output of M-BASIC Program 
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GENERAL INTRODUCTION 


The Microsoft(R) MS(tm)-DOS Programmer's Reference Manual is 


a technical 





reference manual for system programmers. This 
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Chapter 


Chapter 


Chapter 


Chapter 


Chapter 


Chapter 


Ls 


2: 


a description and examples of all MS-DOS 2.0 
system calls and interrupts. 


information on how to install your own device 
drivers on MS-DOS. Two examples of device 
driver programs (one serial and one block) are 
included. 


technical information about MS-DOS, including 
MS-DOS disk allocation, the File Allocation 
Table, and MS-DOS standard disk formats. 


a description of MS-DOS control blocks and 
work areas, including a memory map. 


information on .EXE file structure and loading. 


INTEL(R) object module formats. 
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CHAPTER 1 


SYSTEM CALLS 


1.1 INTRODUCTION 


MS-DOS lets your programs call system routines to manage 
files, devices, system resources, and other programs. These 
system calls save you the trouble of writing your own 
system-management routines, make it eaSier to write 
machine-independent programs, and increase the likelihood 
that your programs will be compatible with future versions 
of MS-DOS. 





There are four general types of system calls: 


1. Input and output to standard character devices: 
Read a character, write a character, read a String, 
write a String, print a character. 


2. File management: Create, open, read, write, close, 
rename, and delete ae file; Create or delete a 
directory, change the current directory. 


3. Program management: End a program, keep a program 
in memory, load and execute another program, 
allocate more memory, release memory. 


4. Miscellaneous system management: Get or set the 
time or date, get the MS-DOS version number, etc. 


System calls include interrupts, which are serviced by 
interrupt handlers, and function requests, which call MS-DOS 
routines. Version 2.0 introduces several new system calls, 
some of which replace earlier ones; the old ones are still 
supported to maintain compatibility with earlier versions of 
MS-DOS, but you should use the new calls unless 
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Circumstances demand that you maintain backward 
compatibility. 


The introduction to this chapter describes tthe difference 
between the old and new system calls, how to execute a 
system call, how to return control to MS-DOS, the format of 
a directory entry, and how each call is described later in 
the chapter. For those who must use the old calls, a 
description of the File Control Block appears toward the end 
of the introduction. The introduction concludes with tables 
that list the interrupts and function requests in numeric 
and alphabetic order. 


The remainder of the chapter consists of a description of 
each interrupt and function request (including a sample 
program), a listing of the macro definitions used in the 
Sample programs, and an extended sample program. 


1.1.1 About Interrupts 


MS-DOS reserves interrupts 20H through 3FH for itS own uSe. 
The table of interrupt routine addresses (vectors) is 


maintained in locations 80H-FCH. Most of the interrupts 
have been superseded by function requests. Descriptions of 
three MS-DOS interrupt handlers (program terminate, 


CONTROL-C, and fatal error) are included in case you must 
write your own routines to handle these interrupts. 


1.1.2 About Function Requests 


The function requests call MS-DOS routines to manage ' system 
resources, As described in the following section, many 
calls added in Version 2x0 supersede older calls, 
particularly in the areas of file handling and program 
Management; some of these calls are compatible with the 
XENIX(TM) operating system. Wherever two calls provide 
essentially the same service, you should use the newer calls 
unless your programs must be backward-compatible with 
earlier versions of MS-DOS. 


1.2 CALLS COMPATIBLE WITH THE XENIX OPERATING SYSTEM 


Version 2.0 adds function requests that provide’ similar 
Capabilities to earlier calls but are compatible with the 
XENIX operating system; they implement the hierarchical 
filing system and make it simpler to manage system resources 
and return control to MS-DOS. Table 1.1 lists these calls. 
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Table 1.1 Function Requests Compatible With the XENIX 
Operating System 





Description Number 
Create Subdirectory 39H 
Remove a Subdirectory 3AH 
Change the Current Directory 3BH 
Create a File 3CH 
Open a File 3DH 
Read from a File or Device 3FH 
Write to a File or Device 40H 
Delete a Directory Entry 41H 
Move a File Pointer 42H 
Change Attributes 43H 
I/O Control for Devices 44H 
Duplicate a File Handle 45H 
Force a Duplicate of a Handle 46H 
Load and Execute a Program 4BH 
Terminate a Process 4CH 
Retrieve Return Code of a Child 4DH 





Unless it's imperative that your program be compatible with 
pre-2.0 versions of MS-DOS, you should use the calls listed 
in Table 1.1. If you do use the older calls, your’. program 
will run under version 2.0, but it will not be able to use 
the features added by version 2.0. 


1.3 USING THE SYSTEM CALLS 
1.3.1 Issuing An Interrupt 


To issue an interrupt, move any required data into’ the 
registers and issue the interrupt. 


1.3.2 Calling A Function Request 


If your program has a standard Program Segment Prefix, 
follow this procedure to call a function request: 


1. Move any required data into the registers. 


2. Move the function number into AH. 
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3. Execute a long call to location 50H in the Program 
Segment Prefix. 


If your program doesn't have a standard Program Segment 
Prefix, follow steps 1 and 2, then issue Interrupt 21H. 


One other technique Supports earlier calling conventions: 
Move any required data into the registers; move the 
function number into CL; and execute an intrasegment call 
to location 05H in the current code segment (this location 
contains a long call to the MS-DOS function dispatcher). 
This method can only be used with functions 00H through 24H, 
and always destroys the contents of AX. 


1.3.3 Using The Calls From A High-Level Language 


The system calls can be executed from any high-level 
language whose modules can be linked with assembly language 
modules. In addition to this general technique: 


You can use the DOSXQQ function of Pascal-86 to 
call a function request directly. 


Use the CALL statement or USER function to execute 
the required 8086 code from the BASIC interpreter. 


1.3.4 Treatment Of Registers 


When MS-DOS takes control after a function call, it switches 
to an internal stack. Registers not used to return 
information (except AX) are preserved. The calling 
program's stack must be large enough to accommodate the 
interrupt system -- at least 128 bytes in addition to other 
needs. 


1.3.5 Error Checking 


Many system calls return a value in ae register’ that 
specifies whether the operation was’ successful, Your 
program can handle error conditions by checking the register 
that contains the error code (usually AX) and_ taking 
appropriate action. 


The calls compatible with the XENIX operating system also 
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set the Carry flag if there is an an error, and identify the 
specific error by returning a number in AX. Table 1.2 lists 
these error codes and their meaning. 


Table 1.2 Error Return Codes 





z 


Meaning 

1 Invalid function number 

2 File not found 

3 Path not found 

4 Too many open files (no open handles left) 
5 Access denied 

6 Invalid handle 

7 Memory control blocks destroyed 

8 Insufficient memory 

9 Invalid memory block address 
10 Invalid environment 
11 Invalid format 
12 Invalid access code 
13 Invalid data 

15 Invalid drive was specified 

16 Attempted to remove the current directory 
17 Not same device 


18 No more files 
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To handle error conditions, put the following statement 
immediately following each call compatible with the XENIX 
operating system: 


JC <error> 


where <error> represents the label of an_ error-handling 
routine that gets the specific error condition by checking 
che value in AX and takes appropriate action. 


1.3.6 Returning Control To MS-DOS 


To return control to MS-DOS, call Function Request 4CH. If 
you want the program to remain in memory, call Function 
Request 31H instead. 


If you must maintain backward compatibility with earlier 
versions of MS-DOS, you can return control to MS-DOS by 
issuing Interrupt 20H, calling Function Request 00H, or 
jumping to location 00H in the Program Segment Prefix. To 
keep the program in memory, issue Interrupt 27H. If you use 
any of these techniques, CS must contain the segment address 
cf the Program Segment Prefix. 
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1.4 HIERARCHICAL DIRECTORY SYSTEM 


MS-DOS version 2.0 supports a hierarchical (multi level) 
directory system, Similar to the XENIX operating system. 
(For information on uSing the multi level directory system, 
see the MS-DOS 2.0 User's Guide.) 


version 2.0 treats the file as a String of bytes, with no 
motion of records, record length, or access’ technique 
(sequential or random). Your programs impose a_= record 
structure on this string of bytes, giving you greater 
flexibility in handling files and simplicity in dealing with 
MS-DOS. 


Table 1.3 lists file-related functions, the function 
requests compatible with the XENIX operating system and the 
corresponding old function request numbers. 


Table 1.3 New and Old File-Related Function Requests 





Function Compatible 
Request With XENIX Old 
Create a file 3CH 16H 
Open a file 3DH OFH 
Close a file 3EH 10H 
Read from a file 3FH 14H, 21H, 27H 
Write to a file 40H 15H, 22H, 28H 
Delete a file 41H 13H 
Move file pointer 42H 24H 
Search directory for first 
matching entry 4EH 11H 
Search directory for next 
Matching entry 4FH 12H 
Rename a file 56H 17H 





MS-DOS does not restrict the depth of a directory structure 
except in the number of allocation units available. The 
root directory has a fixed number of entries (64 for a 
single-sided disk, 112 for a double-sided disk). The number 
of files in all other directories is limited only limited by 
the number of allocation units available. 


Pre-2.0 disks appear to MS-DOS 2.0 as having only a “root 
directory that contains files and no subdirectories. 


Implementation of the multi level directory structure is 
simple. The root directory is the pre-2.0 directory. Each 
subdirectory has a special attribute set indicating that it 
is a directory. The subdirectories themselves are files, 
linked through the FAT as_ uSual. Their entries are 
identical to the entries in the root directory. 


Pre-2.0 directories that use system calls not described in 
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this chapter will be unable to make use of files in other 
directories. Those files not necessary for the current task 
will be placed in other directories. 


1.4.1 Handles 


To create or open a file, you specify a path that identifies 
the drive, directory, name, and extension of the file. 
MS-DOS returns a number called a _ handle. In most cases, 
subsequent actions on this file refer to it only by its 
handle; there is no FCB to maintain. 


A handle can refer to either a file or a device. MS-DOS 
predefines five handles for standard devices; you needn't 
open these devices before using them, Table 1.4 lists these 
predefined handles. 

Table 1.4 Predefined Device Handles 


Handle Standard device 


00H Input 

01H Output 
02H Error 

03H Auxiliary 
04H Printer 





Handles OOH and O1H (Standard input and output) can _ be 
redirected. 
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1.4.2 Directory Entry 


A directory contains one entry for each file on the disk. 
Each entry is 32 bytes. Table 1.5 describes the fields of 
an entry. 


Table 1.5 Format of the Directory Entry 


Size Offset 
Name (bytes) Hex Decimal 
Filename 8 00H 0 
Extension 3 08H 8 
Attributes l OBH ll 
RESERVED 10 OCH 12 
Time of last write 2 16H a2 
Date of last write 2 18H 24 
RESERVED 2 1AH 26 
File size 4 1CH 28 


1.4.3 Fields Of The Directory Entry 


Filename (offset 00H): Eight characters, left-aligned and 
padded (if necessary) with blanks. MS-DOS uses the first 
byte of this field for two special codes: 





OOH End of allocated directory 
E5H Free directory entry 


Extension (offset 08H): Three characters, left-aligned and 
padded (if necessary) with blanks. If there is no 
extension, this field is all blanks. 

Attributes (offset OBH): File attributes (see Table 1.6). 
Reserved (offset OCH): Reserved for MS-DOS. 

Time of Last Write (offset 16H): The time the file was 
created or last updated. The hour, minutes, and seconds are 
mapped into two bytes as follows: 


Offset 17H Offset 16H 


JH|H|H|H/H|M|M|M[ = [M[M[M|s|S|s|s{s| 
15 11 10 5 4 0 
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Date of Last Write (offset 18H): The date the file was 
Created or last updated. The year, month, and day are 
mapped into two bytes as follows: 

Offset 19H Offset 18H 

IyI¥|[yly|y¥|y]y|M]| [M|[M|M|D|D|pD|p|D| 

15 9 8 5 4 0 

File Size (offset 1CH): The size of the file, in bytes. 


The first word of this 4-byte field is the low-order part of 
the size. 


1.4.4 File Attributes 


Table 1.6 describes the file attributes and how they are 
represented in the attribute byte of the directory entry 
(offset OBH). 


Table 1.6 File Attributes 





Attribute Code Comment 


Normal 00H Can be read or written without 
restriction. 

Read-only 01H Attempts to open the file for write or 
create a file with the same name fails. 

Hidden 02H File not found by directory search. Old 
Open File (Function Request OFH) fails. 

System 04H File not found by directory search. Old 
Open File (Function Request OFH) fails. 

Volume-ID 08H Only one file (in the root directory) 
can have this attribute. 

Directory 10H Identifies a subdirectory. Cannot be 


changed with Function Request 43H 
(Change Mode). 
Archive 20H Set when the file is written. 


1.5 SYSTEM CALL DESCRIPTIONS 


Most system calls require that information be moved into one 
Or more registers before the call is issued and return 
information in the registers. The description of each 
system call in this chapter includes the following: 


A drawing of the 8088 registers that shows’ their 
contents before and after the system call. 
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A more complete description of the register 
contents required before the system call. 

A description of the processing performed. 


A more complete description of the register 
contents after the system call. 


An example of its use. 


Figure 1.1 iS an example of the drawing of the 8088 
registers and how the information is presented. 


« [mw Ta] Call 
Return 
Ph 
a ae 
a ae 
ee eee 
PS 
| Fins» | FLAGS. | 
Ce 
a aa 
pss 
oe 


Figure 1.1 Example of System Call Description 


1.5.1 Sample Programs 


The sample programs show only data declarations and the code 
required to use the system calls. Unless stated otherwise, 
each example assumes a common’ skeleton that defines’ the 
segments and returns control to MS-DOS. Each sample program 
is intended to be executed as a COM file. Figure 1.2 shows 
a complete’ sample program. The unshaded portion shows what 
appears in this chapter; the shaded portions are the common 
skeleton. 
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code 


starts 


Loc 50h 


; 
filename 


buffer 
handle 


begin: 


read line: 


return: 
last:inst: 


; 
code 


segment 
assume cs:code,ds:code,es:nothing,ss:nothing 
org 100H 


mov word ptr loc 50h[2],cs 

jmp begin 

label dword 

dw 50h 

dw F 

db "b:\textfile.asc",0 

db L29 dup [{?) 

dw ? 

open handle filename,0 ; Open the file 

jc error open ; Routine net shown 
mov handle,ax > Save handle 

read handle handle,buffer,128 ; Read 128 bytes 
jc error read ; Routine aot shown 
cmp ax,0 | ; End of file? 

je return : Yes, go home 

mov bx,ax ° No, AX bytes read 
MOv buffer [bx],"$" ; To terminate string 
display buffer > See Function 09H 
jmp read line ; Get next 128 bytes 


Return to MS-DOS 
To mark next byte 


end process 0 


=e sme 


ends 
end Start 





Figure 1.2 


Sample Program With Common Skeleton 
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To allow the examples to be more complete programs’ rather 
than isolated uses of the system calls, a macro is defined 
for each system call. These macros are used in the’ sample 
programs; OPEN-HANDLE, READHANDLE, DISPLAY, and ENDPROCESS 
in Figure 1.2 are such macros. A few general-purpose macros 
are also used. All macro definitions are listed at the end 
of this chapter. 


The macros assume the environment for a .COM program as 
described in Chapter 4; in particular, they assume that all 
the segment registers contain the same value. TO conserve 
space, the macros generally do not protect registers and 
leave error checking to the main code. This keeps’~ the 
macros fairly short, yet useful. You may find such macros a 
convenient way to include system calls in your’ assembly 
language programs. 


1.5.2 Error Handling 


Whenever a system call returns an error code, the sample 
program shows atest for the error condition and a jump to 
an error routine. To conserve space, the error’ routines 
themselves aren't shown. Some error routines might simply 
display a message and continue processing; in more’ serious 
cases, the routine might display a message and end the 
program (performing any required housekeeping, such as 
closing files, as required). 
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1.6 FILE CONTROL BLOCK (FCB) 


The old function requests that deal with files require’ that 
your program build and maintain a File Control Block (FCB) 
for each file that contains its name, Size, record length, 
pointer to current record, etc. Each old function request 
that refers to a file must have access to an _ up-to-date 
version of the file's FCB. 


The descriptions refer to unopvened and opened _ FCBs. An 
unopened FCB contains only a drive specifier and filename. 
An opened FCB contains all fields filled by the Open File 
system call (Function OFH). 


The Program Segment Prefix includes room for two FCBS_ at 
offsets 5CH and 6CH. See Chapter 4 for a description of the 
PSP and how these FCBS are used. Table 1.7 describes’ the 
fields of the FCB. 


Table 1.7 Format of the File Control Block (FCB) 





Size Offset 
Name (bytes) Hex Decimal 
Drive number 1 00H 0 
Filename 8 01H 1 
Extension 3 08H 9 
Current block 2 OBH LZ 
Record size 2 ODH 14 
File size 4 OFH 16 
Date of last write 2 13H 20 
Time of last write 2 15H 22 
RESERVED 8 17H 24 
Current record 1 1FH 32 
Relative record 4 20H 33 
1.6.1 Fields Of The FCB 
Drive Number (offset 00H): Specifies the disk drive; 1 





means drive A and 2 means drive B. If the FCB is used to 
create or open a file, this field can be set to 0 to specify 
the default drive; the Open File system call sets the field 
to the number of the default drive. 


Filename (offset 01H): Eight characters, left-aligned and 
padded (if necessary) with blanks. If you specify a 
reserved device name (Such as LPTl), do not put a colon at 
the end. 





Extension (offset 09H): Three characters, left-aligned and 
padded (if necessary) with blanks. This field can be all 





SYSTEM CALLS Page 1-15 


blanks (no extension). 


Current Block (offset OCH): Points to the block (group of 
128 records) that contains the current record. This field 
and the Current Record field (offset 20H) make up the record 


pointer. This field is set to 0 by the Open File system 
call. 


Record Size (offset ODH): The size of a logical record, in 
bytes. Set to 128 by the Open File system call. If the 
record size is not 128 bytes, you must set this field after 
opening the file. 


File Size (offset 10H): The size of the file, in bytes. 
The first word of this 4-byte field is the low-order part of 
the size. 


Date of Last Write (offset 14H): The date the file was 
created or last updated. The year, month, and day are 
mapped into two bytes as follows: 





Offset et 14H 
[el e}y ly iyi] yin] im|mia|o[D|D|D10| 


Time of Last Write (offset 16H): The time the file was 


created or last updated. The hour, minutes, and Seconds are 
mapped into two bytes as follows: 


Offset 17H et 16H 
|H|H|H|H|H|M|M|M| im[mimisisisisis) 
15 1l 10 


Reserved (offset 18H): These fields are reserved for use by 
MS-DOS. 


Current Record (offset 20H): Points to one of the 128 
records in the current block. This field and the Current 
Block field (offset OCH) make up the record pointer. This 
field is not initialized by the Open File system call. You 
must set it before doing a sequential read or write to _ the 
file. 


Relative Record (offset 21H): Points to the currently 
selected record, counting from the beginning of the file 
(starting with 0). This field is not initialized by the 
Open File system call. You must set it before doing a 
random read or write to the file. If the record size is 
less than 64 bytes, both words of this field are used; if 
the record size is 64 bytes or more, only the first three 
bytes are used. 
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NOTE 


If you use the FCB at offset 
5CH of the Program Segment 
Prefix, the last byte of the 
Relative Record field is the 
First byte of the unformatted 
Darameter area that Starts at 
offset 80H. This is the 
default Disk Transfer Area. 


1.6.2 Extended PCB 
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The Extended File Control Block is used to create or search 
for directory entries of files with special attributes. It 
adds the following 7-byte prefix to the FCB: 


Name 


Flag byte (FFH 
Reserved 
Attribute byte 


Size 
(bytes) Offset 


) 1 
5 -06H 
1 


Tables 1.8 through 1.11 list the Interrupts 
Requests in numeric and alphabetic order. 


Function 
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Table 1.8 MS-DOS I 


Interrupt 


20H 
21H 
22H 
23H 
24H 
25H 
26H 
27H 
28H-40H 


Table 1.9 MS-DOS I 


nterrupts, Numeric Order 


Description 


Program Terminate 

Function Request 

Terminate Address 

CONTROL-C Exit Address 
Fatal Error Abort Address 
Absolute Disk Read 

Absolute Disk Write 
Terminate But Stay Resident 
RESERVED 


nterrupts, Alphabetic Order 
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Description 


Absolute Disk Rea 
Absolute Disk Wri 
CONTROL-C Exit Ad 
Fatal Error Abort 
Function Request 
Program Terminate 
RESERVED 
Terminate Address 
Terminate But Sta 


Interrupt 


d 25H 
te 26H 
dress 23H 
Address 24H 
21H 
20H 


22H 
y Resident 27H 
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Table 1.10 


MS-DOS Function Requests, Numeric Order 
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Function 


OOH 
O1H 
02H 
03H 
04H 
05H 
06H 
07H 
08H 
09H 
OAH 
OBH 
OCH 
ODH 
OH 

OFH 
10H 
11H 
12H 


Description 


Terminate Program 

Read Keyboard And Echo 
Display Character 
Auxiliary Input 
Auxiliary Output 

Print Character 

Direct Console I/0 
Direct Console Input 

Read Keyboard 

Display String 

Buffered Keyboard Input 
Check Keyboard Status 
Flush Buffer, Read Keyboard 
Reset Disk 

Select Disk 

Open File 

Close File 

Search For First Entry 
Search For Next Entry 
Delete File 

Sequential Read 
Sequential Write 

Create File 

Rename File 

RESERVED 

Current Disk 

Set Disk Transfer Address 
RESERVED 

Random Read 

Random Write 

File Size 

Set Relative Record 

Set Vector 

Create New Program Segment 
Random Block Read 

Random Block Write 

Parse File Name 

Get Date 

Set Date 

Get time 

Set Time 

Set/Reset Verify Flag 

Get Disk Transfer Address 
Get MS-DOS Version Number 
Keep Process 

RESERVED 

CONTROL-C Check 

RESERVED 

Get Interrupt Vector 

Get Disk Free Space 
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RESERVED 

Return Country-Dependent Information 
Create Sub-Directory 

Remove A Directory Entry 

Change Current Directory 

Create A File 

Open A File 

Close A File Handle 

Read From File Or Device 

Write To A File Or Device 

Delete A Directory Entry 

Move A File Pointer 

Change Attributes 

I/O Control For Devices 

Duplicate A File Handle 

Force A Duplicate Of A Handle 
Return Text Of Current Directory 
Allocate Memory 

Free Allocated Memory 

Modify Allocated Memory Blocks 
Load And Execute A Program 
Terminate A Process 

Return The Return Code Of A Child 
Find Match File 

Step Through A Directory Matching Files 
RESERVED 

Return Current Setting Of Verify 
RESERVED 

Move a Directory Entry 

Get/Set Date/Time Of File 
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Table 1.11 


Function 


48H 
03H 
04H 
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MS-DOS Function Requests, Alphabetic Order 





Descriotion 


Allocate Memory 

Auxiliary Input 

Auxiliary Output 

Buffered Keyboard Input 
Change Attribdutes 

Change Current Directory 
Check Keyboard Status 
Close A File Handle 

Close File 

CONTROL-C Check 

Create A File 

Create File 

Create New Program Segment 
Create Sub-Directory 
Current Disk 

Delete A Directory Entry 
Delete File 

Direct Console Input 
Direct Console I/0 

Display Character 

Display String 

Duplicate A File Handle 
File Size 

Find Match File 

Flush Buffer, Read Keyboard 
Force A Duplicate of a Handle 
Free Allocated Memory 

Get Date 

Get Disk Free Space 

Get Disk Transfer Address 
Get MS-DOS Version Number 
Get Interrupt Vector 

Get Time 

Get/Set Date/Time Of File 
I/O Control For Devices 
Keep Process 

Load And Execute A Program 
Modify Allocated Memory Blocks 
Move A Directory Entry 
Move A File Pointer 
RESERVED 

RESERVED 

RESERVED 

RESERVED 

RESERVED 

RESERVED 

RESERVED 

Open A File 

Open File 

Parse File Name 
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05H Print Character 

27H Random Block Read 

28H Random Block Write 

21H Random Read 

22H Random Write 

3FH Read From File Or Device 

08H Read Keyboard 

01H Read Keyboard And Echo 

3AH Remove A Directory Entry 

17H Rename File 

ODH Reset Disk 

38H Return Country-Dependent Information 
54H Return Current Setting Of Verify 
47H Return Text Of Current Directory 
4DH Return The Return Code Of A Child 
11H Search For First Entry 

12H Search For Next Entry 

OEH Select Disk 

14H Sequential Read 

15H Sequential Write 

2BH Set Date 

1AH Set Disk Transfer Address 

24H Set Relative Record 

2DH Set Time 

25H Set Vector 

2EH Set/Reset Verify Flag 

4FH Step Through A Directory Matching Files 
4CH Terminate A Process 

00H Terminate Program 

40H Write To A File Or Device 


A detailed description of each system call follows. They 
are listed in numeric order; the interrupts are described 
first, then the function requests. 


Note: Unless otherwise stated, all numbers in the-= system 


call descriptions -- both text and code -- are in 
hexadecimal. 


1.7 INTERRUPTS 


The following pages describe Interrupts 20H--27H. 
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Program Terminate (Interrupt 20H) 


Segment address of Program Segment 
Prefix 





Return 
None 


Interrupt 20H causes the current process to terminate and 
returns control to itS parent process. All open file 
handles are closed and the disk cache is’ cleaned. This 
interrupt is almost always is used in old .COM files for 
termination. 


The CS register must contain the segment address of the 
Program Segment Prefix before you call this interrupt. The 
following exit addresses are restored from the Program 
Segment Prefix: 


Exit Address Offset 
Program Terminate OAH 
CONTROL-C OEH 
Critical Error 12H 


All file buffers are flushed to disk. 


NOTE 


Close all files that have 
changed in length before 
issuing this interrupt. If a 
changed file is not closed, 
its length is not’ recorded 
correctly in the directory. 
See Functions 10H and 3EH for 
description of the Close 
File system calls. 


0) 
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Interrupt 20H is provided for compatibility with versions of 
MS-DOS prior to 2.0. New programs’7 should use Function 
Request 4CH, Terminate a Process. 


Macro Definition: terminate macro 
int 20H 


endm 
Example 


The following program displays a message and returns’ to 
MS-DOS. It uses only the opening portion of the sample 
program skeleton shown in Figure 1.2: 


message db "displayed by INT20H example". ODH, OAH, "S$" 


begin: display message ;Ssee Function 09H 
terminate ;THIS INTERRUPT 


code ends 
end Start 
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Function Request (Interrupt 21H) 


«Te Tx] Call 
a fom | ia Function number 
o: | om | oa Other registers as specified in 


individual function 


Return 
As specified in individual function 


A 


The AH register muSt contain the number of the system 
function. See Section 1.8, "Function Requests," for a 
description of the MS-DOS system functions. 


NOTE 
No macro is defined for this 
interrupt, because all 
function descriptions in this 
chapter that define a macro 
include Interrupt 21H. 
Example 


To call the Get Time function: 


Mov ah, 2CH >Get Time is Function 2CH 
call loc_50H :THIS INTERRUPT 


SYSTEM CALLS Interrupt 22H, 23H Page 1-25 


Terminate Address (Interrupt 22H) 
CONTROL-C Exit Address (Interrupt 23H) 
Fatal Error Abort Address (Interrupt 24H) 


These are not true interrupts, but rather storage locations 
for a segment and offset address. The interrupts are issued 
by MS-DOS under the specified circumstance. You can’ change 
any of these addresses with Function Request 25H (Set 
Vector) if you prefer to write your own interrupt handlers. 


Interrupt 22H -- Terminate Address 


When a program terminates, control transfers to the address 
at offset OAH of the Program Segment Prefix. This address 
is copied into the Program Segment Prefix, from the 
Interrupt 22H vector, when the segment is created. 


Interrupt 23H -- CONTROL-C Exit Address 


If the user types CONTROL-C during keyboard input or display 
output, control transfers to the INT 23H vector in the 
interrupt table. This address is copied into the Program 
Segment Prefix, from the Interrupt 23H vector, when the 
segment is created. If the CONTROL-C routine preserves all 
registers, it can end with an IRET instruction (return from 
interrupt) to continue’ program execution. When the 
interrupt occurs, all registers are set to the value they 
had when the original call to MS-DOS was made. There are no 
restrictions on what a CONTROL-C handler can do -- including 
MS-DOS function calls -- so long as the registers are 
unchanged if IRET is used. If Function 09H or OAH (Display 
String or Buffered Keyboard Input) is’ interrupted by 
CONTROL-C, the three-byte sequence 03H-ODH-OAH (ETX-CR-LF) 
is sent to the display and the function resumes at the 
beginning of the next line. If the program creates a new 
segment and loads a second program that changes the 
CONTROL-C address, termination of the second program 
restores the CONTROL-C address to its value before execution 
of the second program. 
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Interrupt 24H -- Fatal Error Abort Address 


If a fatal disk error occurs during execution of one of the 
disk I/O function calls, control transfers to the INT 24H 
vector in the vector table. This address is copied from the 
Interrupt 24H vector into the Program Segment Prefix when 
the segment is created. 


BP:SI contains the address of a Device Header Control Block 
from which additional information can be retrieved. 


NOTE 


Interrupt 24H is not issued if 
the failure occurs during 
execution of Interrupt 257 
(Absolute Disk Read) Or 
Interrupt 26H (Absolute Disk 
Write). These errors are 
usually handled by the MS-DOS 
error routine in COMMAND.COM 
that retries the disk 
Operation, then gives the user 
the choice of aborting, 
retrying the operation, or 
ignoring the error. The 
following topics give you the 
information you need about 
interpreting the error codes, 
Managing the registers and 
stack, and controlling the 
system's response to the error 
in order to write your own 
error-handling routines. 


Error Codes 


When an error-handling program gains control from Interrupt 
24H, the AX and DI registers can contain codes that describe 
the error. If Bit 7 of AH is 1, the error is either a _ bad 
image of the File Allocation Table or an error occurred on a 
character device. The device header passed in BP:SI can _ be 
examined to determine which case exists. If the high-order 
bit of the attribute WORD of the device header indicates a 
block device, then the error was a bad FAT. Otherwise, the 
error iS on a character device. 
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The following are error codes for Interrupt 24H: 


Error Code Description 


Page 1-27 


0 Attempt to write on write-protected 


disk 

Unknown unit 

Drive not ready 
Unknown command 

Data error 

Bad request structure length 
Seek error 

Unknown media type 
Sector not found 
Printer out of paper 
Write fault 

Read fault 

General failure 


AWPUODYHAW PWN! 


The user stack will be in effect (the first item 


described 


below is at the top of the stack), and will contain the 


following from top to bottom: 


IP MS-DOS registers from 
CS issuing INT 24H 


AX User registers at time of original 
BX INT 21H request 


IP From the original INT 21H 
CS from the user to MS-DOS 
FLAGS 


The registers are set such that if an IRET is 
MS-DOS responds according to (AL) as follows: 


executed, 


(AL) =0 ignore the error 


=1] 
=2 


retry the operation 
terminate the program via INT 23H 


Disk Errors 


If the AH 
register 
drive A. 


bit 7 = 0 (there is a hard error on a disk), 
AL contains the failing drive number, with 0 = 
AH bits 0-2 indicate the disk area and whether the 


fail occurred during a read or write operation, as follows: 
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BitO=0 if read operation 
l1 if write operation 


Bits 2-1 (affected disk area) 


0 0 MS-DOS area (system files) 
0 1 File Allocation Table 

1 0 directory 

1 1 data area 


Other Errors 


If AH bit 7 = 1, then the error occurred on a character 
device or resulted from a bad memory image of the File 
Allocation Table. You can examine the device header passed 
in BP:SI to determine the exact cause. If the attribute 
byte high-order bit indicates a block device, then the error 
was a bad FAT. Otherwise, the error is on a character 
device. 


If the error wasS on a character device, the contents of AL 
are unpredictable, and the error code is returned in DI. 


Notes: 


1. For disk errors, this exit is taken only for errors 
occurring during an Interrupt 21H. It is not used 
for errors during Interrupts 25H or 26H. 


2. This routine is entered in a disabled state. 


3. The SS, SP, DS, ES, BX, CX, and DX registers must 
be preserved. 


4. This interrupt handler should refrain from using 
MS-DOS function calls. If necessary, it may use 
calls 01H through OCH. Use of any other call will 
destroy the MS-DOS stack and will leave MS-DOS in 
an unpredictable state. 


5. The interrupt handler must not change the contents 
of the device header. 


6. If the interrupt handler will handle errors’ rather 
than returning to MS-DOS, it should restore the 
application program's registers from the stack, 
remove all but the last three words on the stack, 
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then issue an_ IRET. This will return to the 
program immediately after the INT 21H that 
experienced the error. Note that if this is done, 
MS-DOS will be in an unstable state until a 
function call higher than OCH is issued. 
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Absolute Disk Read (Interrupt 25H) 


[eT] Call 
AL 
Bx: BL 
ae eb Drive number 
DS = BX 
Ox: 
an ae Disk Transfer Address 
CK 
Number of sectors 
DX 


Beginning relative sector 


Return 
AL 

Error code if CF=1 
FlagsL 

CF = 0 1f Successful 


rin 


1 if not successful 


The registers must contain the following: 


AL Drive number (0O=A, 1=B, etc.). 

BX Offset of Disk Transfer Address 
(from Segment address in DS). 

CX Number of sectors to read. 

DX Beginning relative sector. 


This interrupt transfers control to the MS-DOS BIOS. The 
number of sectors specified in CX is read from the disk to 
the Disk Transfer Address. Its requirements and processing 
are identical to Interrupt 26H, except data is read rather 
than written. 


NOTE 


All registers except the 
segment registers are 
destroyed by this call. Be 
Sure to save any registers 
your program uses before 
issuing the interrupt. 


The system pushes the flags at the time of the call; they 


are still there upon return. Be sure to pop the stack upon 
return to prevent uncontrolled growth. 


If the disk operation was successful, the Carry Flag (CF) is 
O. If the disk operation was not successful, CF is 1 and AL 
contains the MS-DOS error code (see Interrupt 24H earlier in 
this section for the codes and their meaning). 
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Macro Definition: 
abs disk read macro disk,buffer,num_sectors,first sector 


mov al,disk 

MOV bx,offset buffer 
Mov cx,num sectors 
mov dx,first sector 
int 25H — 

popf 

endm 


Example 


The following program copies the contents of a_ single-sided 
disk in drive A to the disk in drive B. 


prompt db "Source in A, target in B",0DH,OAH 

db "Any key to start. $" 
first dw 0 
buffer db 60 dup (512 dup (?)) ;60 sectors 
begin: display prompt ;see Function 09H 

read kbd ;see Function 08H 

mov  cx,6 scopy 6 groups of 

760 sectors 

copy: push cx ;save the loop counter 


abs disk read 0,buffer,60,first ;THIS INTERRUPT 
abs disk write 1,buffer,60,first ;see INT 26H 
add first,60 :;do the next 60 sectors 
pop cx ;restore the loop counter 
loop copy 
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Absolute Disk Write (Interrupt 268) 


CF = 0 1f£ successful 
1 if not successful 


«fe px] Call 

5 ee 

se To [a Drive number 

DS :BX 

ox [om | 

Disk Transfer Address 

ae aes CX 
| we Number of sectors 
| DX 
fe Beginning relative sector 
a ae 
| Fiacs. | rss. | Hekues 
ee 
a Error code if CF = 1 
| | SEL 


The registers must contain the following: 


AL Drive number (0=A, 1=B, etc.). 

BX Offset of Disk Transfer Address 
(from segment address in DS). 

CX Number of sectors to write. 

DX Beginning relative sector. 


This interrupt transfers control to MS-DOS. The number of 
sectors specified in CX is written from the Disk Transfer 
Address to the disk. Its requirements and processing are 
identical to Interrupt 25H, except data is written to the 
disk rather than read from it. 


NOTE 
All registers except the 
segment registers are 


destroyed by this call. Be 
Sure to save any registers 
your program uses before 
issuing the interrupt. 


The system pushes the flags at the time of the call; they 
are still there upon return. Be sure to pop the stack upon 
return to prevent uncontrolled growth. i the disk 
operation was successful, the Carry Flag (CF) is 0. If the 
disk operation was not successful, CF is 1 and AL contains 
the MS-DOS error code (see Interrupt 24H for the codes and 
their meaning). 
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Macro Definition: 
abs disk write macro disk,buffer,num_sectors,first sector 


MOV al,disk 

MOV bx,offset buffer 
mov cx,num sectors 
mov dx,first sector 
int 26H 

popf 

endm 


Example 


The following program copies the contents of a_ single-sided 
disk in drive A to the disk in drive B, verifying each 
write. It uses a buffer of 32K bytes. 


of f equ 0 
on equ 1 
prompt db "Source in A, target in B",0DH,0AH 
db "Any key to start. $" 
first dw 0 
buffer db 60 dup (512 dup (?)) 60 sectors 
begin: display prompt ;see Function 09H 
read kbd >see Function 08H 
verify on >see Function 2EH 
Mov cx,6 scopy 6 groups of 60 sectors 
copy: push ox save the loop counter 


abs disk read 0,buffer,60,first ;see INT 25H 
abs disk write 1,buffer,60,first ;THIS INTERRUPT 


add first,60 :do the next 60 sectors 
pop cx ;restore the loop counter 
loop copy 


verify off ;see Function 2EH 
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Terminate But Stay Resident (Interrupt 27H) 


Call 

CS:DX 
First byte following 
last byte of code 


Return 
None 





The Terminate But Stay Resident call is used to 
of code remain resident in the system after its 
Typically, this call is used in .COM files. to 
device-specific interrupt handler to remain 
process asynchronous interrupts. 


make a piece 
termination. 
allow some 
resident to 


DX must contain the offset (from the segment address in CS) 


of the first byte following the last byte of code in the 
program. When Interrupt 27H iS executed, the program 
terminates but iS treated as an extension of MS-DOS; it 
remains resident and is not overlaid by other programs’ when 
it terminates. 

This interrupt is provided for compatibility with versions 


of MS-DOS prior to 2.0. 


31H, Keep Process. 


New programs snould use Function 


Macro Definition: stay resident macro last instruc 


mov dx,offset last instruc 
inc dx 7 

int 27H 

endm 


Example 


7;CS must be equal to PSP values given at program Start 


;(ES ane DS values) 
mMOv DX,LastAddress 
int 27H 


sThere is no return from this interrupt 


SYSTEM CALLS Interrupt 27H Page 1-35 


1.8 FUNCTION REQUESTS 


The following pages describe function calls O0OH-57H. 
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Terminate Program (Function 00H) 


Call 

AH = OOH 

CS 
Segment address of 
Program Segment Prefix 


Return 
None 





Function OOH is called by Interrupt 20H; it performs’ the 
same processing. 


The CS register must contain the Segment address of the 
Program Segment Prefix before you call this interrupt. 


The following exit addresses are restored from the specified 
offsets in the Program Segment Prefix. 


Program terminate OAH 
CONTROL-C OEH 
Critical error 12H 


All file buffers are flushed to disk. 


Warning 


Close all files that have 
changed in length before 
calling this function. If a 
Changed file is not closed, 
its length is not’ recorded 
correctly in the directory. 
See Function 10H for a 
description of the Close File 
system call. 
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Macro Definition: terminate program macro 


XOr ah,ah 
call loc 50H 
endm 


Example 

The following program displays a message and returns’ to 
MS-DOS. It uses only the opening portion of the sample 
program skeleton shown in Figure 1.2. 


message db "Displayed by FUNCOOH example", ODH,OAH,"S" 


begin: display message ;see Function 09H 
terminate program ;THIS FUNCTION 
code ends 


end Start 
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Read Keyboard and Echo (Function 01H) 


Call 
AH = O1H 


AX 
Bx 
Cx: 
OX 
Return 
AL 

Character typed 





Function 01H waits for a character to be typed at the 
keyboard, then echos the character to the display and 


returns it in AL. If the character is CONTROL-C, Interrupt 
23H is executed. 


Macro Definition: read kbd and echo macro 
- ~~ mov ah, O1H 
call loc 50H 
endm 7 


Example 


The following program displays and prints characters as they 
are typed. If RETURN is pressed, the program sends Line 
Feed-Carriage Return to both the display and the printer. 


begin: read kbd and echo ;THIS FUNCTION 
print char al ;see Function 05H 
cmp al,ODH 116. 1h. a CR? 
jne begin no, Print it 
print char OAH ;see Function 05H 
display char OAH ;see Function 02H 


jmp begin ;get another character 
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Display Character (Function 02H) 


Character to be displayed 


Return 
None 


Function 02H displays the character in DL. If CONTROL-C is 
typed, Interrupt 23H is issued. 


Macro Definition: display char macro character 


mov dl,character 
mov ah,02H 

int 21H 

endm 


Example 


The following program converts lowercase characters’ to 
uppercase before displaying them. 


begin: read kbd ;see Function 08H 

cmp al,"a" 

jl uppercase ;don't convert 

cmp aly” a" 

39 uppercase ;don't convert 

sub al, Z0H ;cOonvert to ASCII code 

;for uppercase 

uppercase: display char al ;THIS FUNCTION 


jmp “begin: ;get another character 
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Auxiliary Input (Function 038) 


«Pe Te] Call 

Se 

So 
AL 


Character from auxiliary device 


| i 


Function 03H waits for a character from the auxiliary input 
device, then returns the character in AL. This system call 
does not return a Status or error code. 


If a CONTROL-C has been typed at console input, Interrupt 
23H is issued. 


Macro Definition: aux_input macro 
mov ah,03H 
call loc 50H 
endm 7 


Example 


The following program prints characters as they are received 
from the auxiliary device. It stops printing when an 
end-of-file character (ASCII 26, or CONTROL-Z) is received. 


begin: aux_input ;THIS FUNCTION 
cmp al,1lAH ;end of file? 
je return ;yes, all done 
print char al ;see Function 05H 


jmp begin ;get another character 
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Auxiliary Output (Function 04H) 


Call 
AH = 04H 
DL 
Character for auxiliary device 


AX: 
BX 
Cx 
Ox 


Return 
None 





Function 04H sends the character in DL to the = auxiliary 
Output device. This system call does not return a Status or 
error code. 


If a CONTROL-C has been typed at console input, Interrupt 
23H is issued. 


Macro Definition: aux output macro character 
mov dl,character 
mov ah,04H 
call loc_50H 
endm 


Example 
The following program gets a Series of strings of up to 80 


bytes from the keyboard, sending each to the auxiliary 
device. It stops when a null string (CR only) is typed. 


string db 81 dup(?) ;see Function OAH 
begin: get string 80,string >see Function OAH 
cmp string[l],0 snull string? 
je return syes, all done 
mov cx, word ptr string[l] ;get string length 
mov bx,0 ;set index to 0 
send it: aux_output string[bx+2] *>THIS FUNCTION 
inc bx ;bump index 
loop send it ;send another character 


jmp begin ;get another String 
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Print Character (Function 058) 


Call 
AH = O5H 
DL 
Character for printer 


AX 
BX 
CX: 
Ox 


Return 
None 





Function 05H prints the character in DL on the~ standard 
printer device. If CONTROL-C has’ been typed at console 
input, Interrupt 23H is issued. This function request does 
not return a Status Or error code. 


Macro Definition: print char macro character 
mov dl,character 
mov ah,0O5H 
call loc 50H 
endm 7 


Example 


The following program prints a walking test pattern on the 
printer. It stops if CONTROL-C is pressed. 


line num db 0 
begin: mov cx,60 ;print 60 lines 
Start line: mov DL ,33 ;first printable ASCII 
= ;character (!) 
add bl,line num ;to offset one character 
push cx = ;Save number-of-lines counter 
MOV cx, 80 ;loop counter for line 
Sint it: print char bl ;THIS FUNCTION 
inc bl ;move to next ASCII character 
cmp b1,126 ;last printable ASCII 
;character (7) 
jl no reset snot there yet 


mov b1,33 *start over with (!) 


SYSTEM CALLS 


no _ reset: 
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loop print it ;print another character 
print char ODH ;Carriage return 
print char OAH ;line feed 
inc line num ;to offset lst char. of line 
pop cx | ;restore #-of-lines counter 
loop start line ;print another line 
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Direct Console I/O (Function 06H) 


Call 
AH = 06H 
DL 

See text 


Return 
AL 
If DL = FFH before call, 


Character from keyboard. 


The processing depends on the value in DL when the 
is called. 


DL is FFH -- If a character has been typed 
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then Zero flag set means AL has 


Zero flag not set means there was 
not a character to get, and AL = 0 


function 


at the 


keyboard, it is returned in AL and the Zero flag is 


0; if a character has not been typed, 
flag is l. 


the Zero 


DL iS not FFH -- The character in DL is displayed. 


This function does not check for CONTROL-C. 


Macro Definition: dir console io macro switch 
7 > mov dl,switch 
mov ah,06H 
call loc 50H 
endm > 
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Example 


The following program sets the system clock to 0 and 
continuously displays the time. When any character is 
typed, the display stops changing; when any character is 


typed again, the clock is reset to 0 and the display starts 
again. 


time db "00:00:00.00",0DH,0AH,"S$" ;see Function 09H 

; ;for explanation of $ 

ten db 10 

begin: set time 0,0,0,0 >see Function 2DH 

read clock: get _time ;see Function 2CH 
convert ch,ten,time ;see end of chapter 
convert cl,ten,time[3] ;see end of chapter 


convert dh,ten,time[6] ;see end of chapter 
convert dl,ten,time[9] ;see end of chapter 


display time ;see Function 09H 
dir console io FFH ;THIS FUNCTION 
cmp al,0 ;character typed? 
jne stop ;yes, stop timer 
jmp read clock sno, keep timer 
7 ;running 
stop: read_ kbd ;see Function 08H 


jmp begin ;Sstart over 
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Direct Console Input (Function 07H) 





Character from keyboard 


Function 07H waits for a character to be typed, then returns 
it in Als This function does not echo the character or 
check for CONTROL-C. (For a keyboard input function that 
echoes or checks for CONTROL-C, see Function 01H or O8H.) 


Macro Definition: dir console input macro 
mov ah,07H 
call loc_50H 


endm 
Example 
The following program prompts for a password (8 characters 
maximum) and places the characters into a String without 
echoing them. 
Password db- 8 dup(?) 
prompt db "Password: $" ;see Function 09H for 
7;explanation of $ 
begin: display prompt ;see Function 09H 
mov cx,8 ;maximum length of password 
xOr bx,bx >So BL can be used as index 
get pass: dir console input ;THIS FUNCTION 
i cmp al,0DH swas it a CR? 
je return ;yes, all done 
mov password([bx],al ;no, put character in string 
inc bx ;bump index 


loop get pass ;get another character 
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Read Keyboard (Function 088) 


Call 
AH = 08H 





Return 
AL 
Character from keyboard 


[recs | PAGS. | 

cae | 

pss 

a aes) 
Function 08H waits for a character to be typed, then returns 
it in AL. If CONTROL-C iS pressed, Interrupt 23H is 
executed. This function does not echo the character. (For 


a keyboard input function that echoes’ the character or 
checks for CONTROL-C, see Functions 01H.) 


Macro Definition: read kbd macro 
i mov ah,08H 
Call loc 50H 
endm = 


Example 
The following program prompts for a password (8 characters 
maximum) and places the characters into a string without 


echoing them. 


password db 8 dup(?) 


prompt db "Password: $" ;see Function 09H 
;for explanation of $ 
begin: display prompt ;see Function 09H 
mov cx,8 ;maximum length of password 
xOr bx,bx ;BL can be an index 
get pass: read kbd ;THIS FUNCTION 
7 cmp al,0ODH ;was it a CR? 
je return ;yes, all done 
mov password[bx],al ;no, put char. in String 
inc bx >bump index 


loop get pass ;get another character 
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Display String (Function 09H) 


«fm Tx] Call 
x [em | a | AH = 09H 
a DS : DX 
ox [| om | mo | String to be displayed 
ee es 
oe Return 
aa ae None 
ae ase 
ee Se 
[| rusas. | ruacs. | 
ae 
ee eee 
a eee 
a Bae 


DX must contain the offset (from the segment address in DS) 
of a string that ends with "$". The String is displayed 
(the $ is not displayed). 


Macro Definition: display macro string 
mov dx,offset string 
mMOv ah,09H 
call loc_50H 
endm 


Example 


The following program displays the hexadecimal code of the 
key that is typed. 


table db "0123456789ABCDEF" 

Sixteen db 10H 

result db - 00H",ODH,OAH,"S$" ;see text for 
;explanation of §$ 


begin: read kbd and echo ;see Function 01H 
convert al,sixteen,result[3] ;see end of chapter 
display result ;THIS FUNCTION 


jmp begin ;do it again 
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Buffered Keyboard Input (Function OAH) 


Call 
AH = OAH 
DS :DX 
Input buffer 





Return 
None 


DX must contain the offset (from the segment address in DS) 
of an input buffer of the following form: 


Byte Contents 


1 Maximum number of characters in buffer, including 
the carriage return (you must set this value). 


Zz Actual number of characters typed, not counting 
the carriage return (the function sets this value). 


3-n Buffer; must be at least as long as the number 
in byte l. 
This function waits for characters to be typed. Characters 


are read from the keyboard and placed in the _ buffer 
beginning at the third byte until RETURN is pressed. If the 
buffer fills to one less than the maximum, additional 
characters typed are ignored and ASCII 7 (BEL) is_ sent’ to 
the display until RETURN is' pressed. The string can be 
edited as it is being entered. If CONTROL-C is’ typed, 
Interrupt 23H is issued. 


The second byte of the buffer is set to the number of 
characters entered (not counting the carriage return). 


Macro Definition: get string macro limit,string 


mov dx,offset string 
mov String,limit 
mov ah, OAH 


call loc_50H 
endm 


SYSTEM CALLS 


Example 
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The following program gets a 16-byte (maximum) string’ from 
the keyboard and fills a 24-line by 80-character screen with 


it. 

buffer label byte 

max length db ? ;maximum length 

chars entered db ? snumber of chars. 

string db LT dup (3) >16 chars + CR 

strings per line dw 0 ;how many strings 
;fit on line 

cr Lt db ODH, OAH 

begin: get string 17,buffer *>THIS FUNCTION 


display screen: 


display line: 


xor bx,bx ;Sso byte can be 
;used as index 
mov bl,chars entered ;get string length 


mov buffer[bx+2],"$"  ;see Function 09H 

mov al,50H ;columns per line 

cbw 

div chars entered ;times string fits 
7 on line 

xOor ah,ah ;clear remainder 

mov strings per line,ax ;save col. counter 

mov cx,24 *row counter 

push cx ;Save it 

mov cx,Strings per line ;get col. counter 

display string ~— ;see Function 09H 

loop display line 

display crlf- ;see Function 09H 

pop. cx ;get line counter 


loop display screen ;display 1 more line 
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Check Keyboard Status (Function OBA) 


«Te Ta] Call 
ox [eo [= | AH = OBH 
o: | ow | oe are 
ee AL 
| eS FFH = characters in type-ahead 
ae eee buffer 
an Sa 0 = no characters in type-ahead 
ease ae ice 
LFiacs» | Fiacs: | 
ae 
ae ee 
ae 
ae 


Checks whether there are characters in the’ type-ahead 
buffer. If so, AL returns FFH; if not, AL returns 0. If 
CONTROL-C is in the buffer, Interrupt 23H is executed. 


Macro Definition: check kbd status macro 
mov ah,0OBH 
call loc_50H 
endm 7 


Example 


The following program continuously displays the time until 
any key is pressed. 


time db "00:00:00.00",0DH,0AH,"$" 

ten db OAH 

begin: get time ;see Function 2CH 
convert ch,ten,time ;see end of chapter 
convert cl,ten,time [3] s;see end of chapter 
convert dh,ten,time[6] >see end of chapter 
convert dl,ten,time[9}] s;see end of chapter 
display time ;see Function 09H 
check kbd status ;THIS FUNCTION 
cmp al,OFFH shas a key been typed? 
je return ;yes, go home 
jmp begin ;no, keep displaying 


: time 
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Flush Buffer, Read Keyboard (Function OCH) 


Call 

AH = OCH 

AL 
Ly 6+ 7, 8, Or OAH = the 
corresponding function 





SP is called. 
ne aa Any other value = no 
po further processing. 
ae ae Return 


rcs a 


0 = Type-ahead buffer was 


Tos flushed; no other 
Pp 
ee 


processing performed. 


The keyboard type-ahead buffer is emptied. Further 
processing depends’ on the value in AL when the function is 
called. 


1, 6, 7, 8, Or OAH -- The corresponding MS-DOS 
function is executed. 


Any other value -- No further processing; AL 
returns OQ. 


Macro Definition: flush and_read_kbd macro switch 
mov al,Sswitch 
mov ah,0CH 
cail loc 506 
endm 7 


Example 


The following program both displays and prints characters as 
they are typed. If RETURN is pressed, the program sends 
Carriage Return-Line Feed to both the display and_ the 
printer. 


begin: flush_and_read kbd 1 ; THIS FUNCTION 
print char al ;see Function 05H 
cmp al,ODH :1S 1t a CR? 
jne begin no, print it 
print char OAH ;see Function 05H 
display char OAH ;see Function 02H 


jmp begin ;get another character 
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Disk Reset (Function ODA) 


Call 
AH = ODH 


AX 
Bx: 
Cx: 
OX: 
Return 
None 





Function ODH is used to ensure that the internal buffer 
cache matches the disks in the drives. This function writes 
out dirty buffers (buffers that have been modified), and 
marks all buffers in the internal cache as free. 


Function ODH flushes all file buffers. It does not update 
directory entries; you must close files that have changed 
to update their directory entries (see Function 10H, Close 
File). This function need not be called before a disk 
change if all files that changed were _ closed. It is 
generally used to force a known state of the system; 
CONTROL-C interrupt handlers should call this function. 


Macro Definition: reset disk macro 
~ mMOv ah,ODH 
call loc 50H 
endm a 


Example 


The following program flushes all file buffers and_ selects 
disk A. 


begin: reset disk 
Select disk "A" 


SYSTEM CALLS 


Function OEH 


Select Disk (Function OER) 


AX 
Bx 
Cx CH Cc 


OX: 


Call 

AH = 

DL 
Drive number 
(0 = A, 1=B, 


OEH 


etc.) 


Return 
AL 
Number of logical drives 


The drive specified in DL 
as the default disk. 
AL. 


For future 


(O = A, 1 


= B, etc.) is 
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selected 


The number of drives is returned in 


NOTE 


the 


value 
treated 
instance, if 
is not safe to 
Ay By Cy 


compatibility 
returned 
with 


in AL must be 
care. FOr 
AL returns 5 it 
assume drives 
D, E are all valid 


drive designators. 


Macro Definition: 


select disk macro disk 


mov d1,disk[-64] 
mov ah,0OEH 
call loc 50H 


endm 
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Example 


The following program selects the drive not 
selected in a 2-drive system. 


begin: Current disk ;see Function 19H 
cmp al,0O0H ;drive A: selected? 
je select _b ;yes, select B 
select disk "A” ;THIS FUNCTION 
jmp return 


select _b: select disk "B" ;THIS FUNCTION 
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currently 
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Open File (Function OFH) 


Call 
AH = OFH 
DS :DX 
Unopened FCB 


AX: 
Bx: 
Cx: 
Dx: 


Return 
AL 
0 = Directory entry found 
FFH = No directory entry found 


: 
fi re 


DX must contain the offset (from the segment address in DS) 
of an unopened File Control Block (FCB). The disk directory 
is searched for the named file. 


If a directory entry for the file is found, AL returns 0 and 
the FCB is filled as follows. 


If the drive code was 0 (default disk), it is 
changed to the actual disk used (l = A, 2 = B, 
etc.). This lets you change the default disk 
without interfering with subSequent operations on 
this file. 


The Current Block field (offset OCH) is set to 
zero. 


The Record Size (offset OEH) 1S set to the system 
default of 128. 


The File Size (offset 10H), Date of Last Write 
(offset 14H), and Time of Last Write (offset 16H) 
are set from the directory entry. 


Before performing a sequential disk operation on the _ file, 
you must set the Current Record field (offset 20H). Before 
performing a random disk operation on the file, you must set 
the Relative Record field (offset 21H). If the default 
record size (128 bytes) is not correct, set it to the 
correct length. 


If a directory entry for the file is not found, AL returns 
PFH. 
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Macro Definition: open macro fcb 
mov dx,offset fcb 
mov ah,OFH 
call loc 50H 
endm pS 


Example 


The following program prints the file named TEXTFILE.ASC 
that is on the disk in drive B. If a partial record is in 
the buffer at end-of-file, the routine that prints’ the 
partial record prints characters until it encounters an 
end-of-file mark (ASCII 26, or CONTROL-Z). 


fcb db 2,"TEXTFILEASC" 
db 26 dup (?) 
buffer db 128 dup (?) 
begin: set dta buffer ;see Function l1AH 
open fcb ;THIS FUNCTION 
read line: read seq fcb ;see Function 14H 
= cmp a1,02H send of file? 
je all _ done syes, go home 
cmp al,00OH smore to come? 
jg check more ;no, check for partial 
7 srecord 
mov cx, 80H ;yes, print the buffer 
XOL si,si set index to 0 
praak it: print char buffer[si] ;see Function 05H 
inc si ;bump index 
loop print it sprint next character 
jmp read line *read another record 
check more: cmp al,03H ;part. record to print? 
7 jne all done ;no 
mov cx, 80H ;yes, print it 
xOr Si,Si set index to 0 
find eof: cmp buffer[si] ,26 send-of-file mark? 
a je all _ done yes 
print char buffer[si] ;see Function 05H 
inc si ;bump index to next 
;Character 


loop find eof 
all done: close fcb ;see Function 10H 
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Close File (Function 108) 


« [me Ta] Call 

x [im | a | AH = 10H 

a [ow [oa | DS : DX 

o [ow [om | Pee aCe 
Return 
AL 


0 = Directory entry found 
FFH = No directory entry found 


DX must contain the offset (to the segment address in DS) of 
an opened FCB. The disk directory is searched for the file 
named in the FCB. This function must be called after a file 
is changed to update the directory entry. It is strongl 
advised that any FCB (even one for a file that hasn't been 
changed) be closed when access to the file is no longer 
needed. 


If a directory entry for the file is found, the location of 
the file is compared with the corresponding entries in the 
FCB. The directory entry is updated, if necessary, to match 
the FCB, and AL returns 0. 


If a directory entry for the file is not found, AL returns 
FFH e 


Macro Definition: close macro fcb 
mov dx,offset fcb 
MOV ah,10H 
call loc 50H 
endm a 


Example 
The following program checks the first byte of the file 


named MOD1.BAS in drive B to see if it is FFH, and prints a 
message if it is. 


message db "Not saved in ASCII format",0ODH,OAH,"$" 
fcb db 2,"MOD1 BAS" 

db 26 dup (?) 
buffer db 128 dup (?) 


begin: set_dta buffer ;see Function 1AH 


SYSTEM CALLS 


all done: 


close fcb 


;THIS FUNCTION 
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fcb >see Function OFH 
read seq _ fcb :;see Function 14H 
buffer,OFFH ;is first byte FFH? 
all done :no 
display message >see Function 09H 
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Search for First Entry (Function 118) 


[om Ta] Call 

x [oe [a AH = 11H 

o [oom [oa | BS: Dx 

o: [| ow [ oo | Unopened FCB 


Return 
AL 
0 = Directory entry found 
FFH = No directory entry found 


DX must contain the offset (from the segment address in DS) 
of an unopened FCB. The disk directory is searched for the 
first matching name. The name can have the (?) wild card 
character to match any character. To search for hidden or 
system files, DX must point to the first byte of an extended 
FCB prefix. 


If a directory entry for the filename in the FCB is7~ found, 
AL returns O and an unopened FCB of the same type (normal or 
extended) is created at the Disk Transfer Address. 


If a directory entry for the filename in the FCB is- not 
found, AL returns FFH. 


The original FCB at DS:DX contains information to continue 
the search with Function 12H. This FCB must not be altered 
Or opened. 


Notes: 


If an extended FCB is used, the following Search pattern is 
used: 


po 


If the FCB attribute iS zero, only normal _ file 
entries are found. Entries for volume label, 
Subdirectories, hidden, and system files will not 
be returned. 
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as 


If the attribute field is set for hidden or’ system 
files, Or directory entries, it is to be considered 
aS an inclusive search. All normal file entries 
plus all entries matching the specified attributes 
are returned. To look at all directory entries 
except the volume label, the attribute byte may be 
set to hidden + system + directory (all 3 bits on). 


If the attribute field is set for the volume label, 
it is considered an exclusive search, and only the 
volume label entry is returned. 


Macro Definition: search first macro fcb 


Example 


MOv dx,offset fcb 
mov ah,1llH 

call loc_50H 

endm 


The following program verifies the existence of a file named 
REPORT.ASM on the disk in drive B. 


yes db “FILE EXISTS.$" 

no db "FILE DOES NOT EXIST.$" 

erlt db ODH,OAH,"$" 

Ech db 2,"REPORT ASM" 
db 26 dup (?) 

buffer db 128 dup (?) 

begin: set dta buffer ;see Function 1AH 
search first fcb ;THIS FUNCTION 
cmp al,OFFH ;directory entry found? 
je not there ;no 
display yes ;see Function 09H 
jmp continue 

not there: display no ;see Function 09H 

continue: display crlf ;see Function 09H 
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Search for Next Entry (Function 12h) 


Call 

AH = 12H 

DS :DX 

Unopened FCB 


AX 
Bx 
Cx 
DX: 


Return 


0 = Directory entry found 
FFH = No directory entry found 


DX must contain the offset (from the segment address in _ DS) 
of an FCB”) previously specified in a call to Function 11H. 
Function 12H is used after Function 11H (Search for First 
Entry) to find additional directory entries that match a 
filename that contains wild card characters. The disk 
directory is searched for the next matching name. The name 
can have the (?) wild card character to match any character. 
To search for hidden or system files, DX musSt point to the 
first byte of an extended FCB prefix. 


If a directory entry for the filename in the FCB is_~ found, 
AL returns 0 and an unopened FCB of the same type (normal or 
extended) is created at the Disk Transfer Address. 


If a directory entry for the filename in the FCB is- not 
found, AL returns FFH. 


Macro Definition: search next macro fcb 
mov dx,offset fcb 
mov ah,12H 
call loc 50H 
endm — 


Example 


The following program displays the number of files on _ the 
disk in drive B. 


message db "No files",0ODH,OAH,"S$" 
files db 0 
ten db OAH 
fcb db ip Peeterrerc2z2” 
db 26 dup (?) 


buffer db 128 dup (?) 
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begin: set dta buffer ;see Function lAH 
Search first fcb see Function 11H 
cmp al,0OFFH ;directory entry found? 
je all done sno, no files on disk 
inc files ;yes, increment file 
s;counter 
search dir: search next’ fcb ;THIS FUNCTION 
cup al,OFFH ;directory entry found? 
je done ;no 
inc files syes, increment file 
;counter 
jmp search dir ;check again 
done: convert files,ten,message ;see end of chapter 


all done: display message ;see Function 09H 
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Delete File (Function 13H) 


wT] Call 
ce [=| MB 13 

a a 
<a 


Unopened FCB 


Ce Return 

ss AL 

ie. ae 0 = Directory entry found 

a rs FFH = No directory entry found 
| Fuacs. | FLAGS. 

MA Se 

a ee 


DX must contain the offset (from the segment address in DS) 
of an unopened FCB. The directory is searched for a 
matching filename. The filename in the FCB can contain’ the 
(?) wild card character to match any character. 


If a matching directory entry is found, it is deleted from 
the directory. If the "?" wild card character is used in 
the filename, all matching directory entries are deleted. 
AL returns 0. 


If no matching directory entry is found, AL returns FFH. 


Macro Definition: delete macro’ fcb 


mov dx,offset fcb 
mov ah,13H 

Cail Loc. 50H 

endm - 


Example 


The following program deletes each file on the disk in drive 
B that was last written before December 31, 1982. 


year dw 1982 

month db L2 

day db a 

files db 0 

ten db OAH 

message db "NO FILES DELETED.",0DH,0AH,"$" 
fcb db De eeeeeereree 


db 26 dup (?) 
buffer db 128 dup (?) 


e 
e 


SYSTEM CALLS 


begin: 


compare: 


next: 


all done: 
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set dta buffer >see Function 1lAH 
search first fcb ;see Function 11H 
cnp al,0OFFH ;directory entry found? 
je all _done 7no, no files on disk 
convert date buffer ;see end of chapter 
camp cx,year snext several lines 
39 next ;check date in directory 
cmp dl,month ;entry against date 
39 next ;above & check next file 
cnp dh,day ;if date in directory 
jge next sentry isn't earlier. 
delete buffer ;THIS FUNCTION 
inc files ;bump deleted-files 

;counter 

search next fcb ;see Function 12H 
cnp al,00H ;directory entry found? 
je compare syes, check date 
cmp files,0 sany files deleted? 
je all_done ;no, display NO FILES 


;message. 
convert files,ten,message ;see end of chapter 
display message ;see Function 09H 
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Sequential Read (Function 148) 


BX: AH = 14H 
Cx: DS : DX 


Opened FCB 


Return 


fn) 

io) 
29) 
i) 


Read completed successfully 
EOF 

DTA too small 

EOF, partial record 


>) 

N 

2) 
nou tt 


P 


DX must contain the offset (from the segment address in DS) 
of an opened FCB. The record pointed to by the Current 
Block (offset OCH) and Current Record (offset 20H) fields is 
loaded at the Disk Transfer Address, then the Current Block 
and Current Record fields are incremented. 


The record size is set to the value at offset OEH in the 
FCB e 


AL returns a code that describes the processing: 


Code Meaning 
0 Read completed successfully. 
1 End-of-file, no data in the record. 
fe Not enough room at the Disk Transfer Address 


to read one record; read canceled. 


3 End-of-file; a partial record was read and 
padded to the record length with zeros. 


Macro Definition: read seq macro fcb 
Mov dx,offset fcb 
Mov ah,14H 
call loc 50H 
endm = 


SYSTEM CALLS Function 14H Page 1-67 


Example 


The following program displays the file named TEXTFILE.ASC 
that is on the disk in drive B; its function is similar to 
the MS-DOS TYPE command. If a partial record is in the 
buffer at end of file, the routine that displays the partial 
record displays characters until it encounters an 
end-of-file mark (ASCII 26, or CONTROL-Z). 


fcb db 2," TEXTFILEASC" 
db 26 dup (?) 
buffer db 128 dup (?7).,"s* 
begin: set dta buffer ;see Function 1AH 
open fcb see Function OFH 
read line: read seq fcb ;THIS FUNCTION 
cmp al,0O2H :;DTA too small? 
je all done ;yes 
cmp a1,00H ;end-of-fFile? 
jg check more ;yes 
display buffer ;see Function 09H 
jmp read line ;get another record 
check more: cmp al,03H spartial record in buffer? 
jne all done ;no, go home 
xOr si,si :set index to 0 
find eof: cmp buffer[si],26 ;ig character EOF? 
je all _ done ;yes, no more to display 
display char buffer[si] ;see Function 02H 
inc si ;bump index 
jmp find eof ;check next character 


all done: close fcb ;see Function 10H 
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Sequential Write (Function 15H) 


aX: Call 
BX: AH = 15H 
Cx: DS :DX 
jigs Opened FCB 
Return 
AL 
OOH = Write completed successfully 
O1H = Disk full 
02H = DTA too small 





DX must contain the offset (from the Segment address in DS) 
of an opened FCB. The record pointed to by Current Block 
(offset OCH) and Current Record (offSet 20H) fields is 
written from the Disk Transfer Address, then the current 
block and current record fields are incremented. 


The record size is set to the value at offset OEH in the 
FCB. If the Record Size is less than a sector, the data at 
the Disk Transfer Address iS written to ae buffer; the 
buffer is written to disk when it contains a full sector of 
data, or the file is closed, or a Reset Disk system call 
(Function ODH) is issued. 


AL returns a code that describes the processing: 


Code Meaning 
0 Transfer completed successfully. 
1 Disk full; write canceled. 
2 Not enough room at the Disk Transfer Address 


to write one record; write canceled 


Macro Definition: write seq macro fcb 
MOV dx,offset ficb 
mov ah,15H 
call loc 5SOH 
endm > 


SYSTEM CALLS 


Example 


The following program creates a file named DIR.TMP- on 
disk in drive B that contains the disk number 


etc.) 


record size 


fon i 
fcb2 
buf fer 


begin: 


write it: 


all done: 


equ OEH 
db Zi, DIR TMP" 
db 26 dup {(?) 
db Be PETC SR S22 FT 2S" 
db 26 dup (?) 
db 128 dup (?) 
set dta buffer 
search first fcb2 
cp al,OFFH 
je all done 
create fcbl 
mMOv 
write seq fobl 
cmp ai, 
jne all_ done 
search next fcb2 
cmp al,FFH 
je all done 
jmp write it 
close febl 
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the 


(0 = A, 1 =B, 


and filename from each directory entry on the disk. 


-offset of Record Size 
field in FCB 


>see Function 1AH 

>see Function 11H 
;directory entry found? 
sno, no files on disk 
;see Function 16H 


fobl[([record size] ,12 


sset record size to 12 
*THIS FUNCTION 

swrite successful? 

7;no, go home 

>see Function 12H 
;directory entry found? 
;no, go home 

;yes, write the record 
>see Function 10H 
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Create File (Function 16H) 


Call 
AH = 16H 
DS :DX 
Unopened FCB 


AX 

Bx: 
Cx: 
Ox: 


Return 

AL 
OOH = Empty directory found 
FFH = No empty directory 


available 





DX must contain the offset (from the segment address in DS) 
of an unopened FCB. The directory is searched for an empty 
entry Or an exiSting entry for the specified filename. 


If an empty directory entry is found, it is initialized to a 
zero-length file, the Open File system call (Function OFH) 
is called, and AL returns 0. You can create a hidden file 
by uSing an extended FCB with the attribute byte (offset 
FCB-1l) set to 2. 


If an entry is found for the specified filename, all data in 
the file is released, making a zero-length file, and the 
Open File system call (Function OFH) is issued for the 
filename (in other words, if you try to create a file that 
already exists, the existing file is erased, and a new, 
empty file is created). 


If an empty directory entry is not found and there is no 
entry for the specified filename, AL returns FFH. 


Macro Definition: create macro fcb 
MOV dx, offset fcb 
mov ah,16H 
call loc 50H 
endm 
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Example 


The following program creates a file named DIR.TMP on the 
disk in drive B that contains the disk number (0 = A, 1 =B, 
etc.) and filename from each directory entry on the disk. 


record size equ OEH ;0ffset of Record Size 
: field of FCB 
fcbl db 2; "DIR TMP" 
db 26 dup (?) 
fcb2 db Pe Peeteretire 
db 26 dup (?) 
buffer db 128 dup (?) 
begin: set dta buffer ;see Function l1AH 
search first fcb2 ;see Function 11H 
cmp al,OFFH ;directory entry found? 
je all done sno, no files on disk 
create fcbl ;THIS FUNCTION 
mov fcbl[{record size],12 
“yset record size to 12 
write it: write seq fcbl ;see Function 15H 
cmp al,0 ;write successful 
jne all done >no, go home 
search next £Fcb2 >see Function 12H 
cmp § al,FFH ;directory entry found? 
je all done ;no, go home 
jmp write it ;yes, write the record 


all done: close fcbl ;see Function 10H 


SYSTEM CALLS Function 17H Page 1-72 


Rename File (Function 178) 


Call 
AH = 17H 
DS: Dx 
Modified FCB 


AX 
Bx 
Cx 


Ox 


Return 

AL 
OOH = Directory entry found 
FFH = No directory entry 
found or destination already 
exists 





DX must contain the offset (from the segment address in DS) 
of an FCB with the drive number and filename filled in, 
followed by a second filename at offset 11H. Tne disk 
directory is searched for an entry that matches the first 
filename, which can contain the (?) wild card character. 


If a matching directory entry is found, the filename in the 
directory entry is changed to match the second filename in 
the modified FCB (the two filenames cannot be the- same 
name). If the "?" wild card character is used in the second 
filename, the corresponding characters in the filename of 
the directory entry are not changed. AL returns 0. 


If a matching directory entry is not found or an entry is 
found for the second filename, AL returns FFH. 


Macro Definition: rename macro fcb,newname 
MOV dx,offset ficb 
mov ah,17H 
Cail loc 50H 
endm i 


SYSTEM CALLS 


Example 


Function 17H 


The following program prompts for the name of 


new name, 


fcb 
promptl 
prompt2 
reply 
CELE 


begin: 


then renames the file. 


db 37 dup (?) 


db "Filename: $" 

db "New name: S$" 

db 15 dup(?) 

db ODH,OAH,"S$" 

display promptl ;see 

get string 15,reply ;see 

display crlf ;see 

parse reply[2],fcb ;see 

display prompt2 ;see 

get string 15,reply ;see 

display crlf ;see 

parse reply[2],fcb[16] 
7;see 

rename ran 
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a file 


Function 
Function 
Function 
Function 
Function 
Function 
Function 


Function 


and 


09H 
OAH 
09H 
29H 
09H 
OAH 
09H 


29H 


;THIS FUNCTION. 


a 
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Current Disk (Function 19H) 


Call 
AH = 19H 


Return 

AL 
Currently selected drive 
(0 = A, 1 = B, ete.) 





AL returns the currently selected drive (0 = A, i = 8, 
Cte.) <« 


Macro Definition: current disk macro 
mov ah,19H 
call loc 50H 
endm = 


Example 


The following program disptays the currently selected 
(default) drive in a 2-drive system. 


message db “Current disk is $”* 

erlt db ODE OAH, "Ss" 

begin: display message ;see Function 09H 
current disk ; THIS FUNCTION 
cmp al,0O0OH -is it disk A? 
jne disk _b sno, it's disk B: 
display char "A" ;see Function 02H 
jmp ~ all done 

disk b: display char "B" ;see Function 02H 


all done: display crlf >see Function 09H 


SYSTEM CALLS Function 1AH Page 1-75 


Set Disk Transfer Address (Function 1A) 


Call 
AH = 1AH 
DS : DX 
Disk Transfer Address 


Return 
None 





DX must contain the offset (from the segment address in DS) 
of the Disk Transfer Address. Disk transfers cannot wrap 
around from the end of the segment to the beginning, nor can 
they overflow into another segment. 


NOTE 


If you do not set the Disk 
Transfer Address, MS-DOS 
defaults to offset 80H in the 
Program Segment Prefix. 


Macro Definition: set dta macro buffer 
a mov dx,offset buffer 
mov ah, 1AH 
call loc_50H 
endm 
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The following program prompts for a letter, converts’ the 
letter to its alphabetic sequence (A = 1, B = 2, etc.), then 
reads and displays the corresponding record from ae file 
named ALPHABET.DAT on the disk in drive B. The file 


contains 26 records; 


each record is 28 bytes long. 


record size equ OEH ;offset of Record Size 
7 ;field of FCB 
relative record equ 21H -offset of Relative Record 
: 7 field of FCB 
fcb db 2," ALPHABETDAT" 
db 26 dup (?) 
buf fer db 28 duot?),"s” 
prompt db "Enter letter: $" 
erle db ODH, OAH, "S$* 
begin: set dta buffer ;THIS FUNCTION 
open fcb ;see Function OFH 
mov feb[record size],28 ;set record size 
get char: display prompt ;see Function 09H 
read kbd and echo ;see Function 01H 
cmp ‘al,ODH ;just a CR? 
je all done ;yes, go home 
sub al,41H ;convert ASCII 
7;cOde to record # 
mov feb[relative record] ,al 
;set relative record 
display crlf ;see Function 09H 
read ran fcb ;see Function 21H 
display buffer ;see Function 09H 
display crlf ;see Function 09H 
jmp get _char ;get another character 
all done: close Fcb ;see Function 10H 
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Random Read (Function 21H) 





AX: Call 
a AH = 21H 
cx: DS :DX 
se Opened FCB 
a ae 
a ae Return 
a sa AL 
Fm OOH = Read completed successfully 
| ee 
O2H = DTA too small 
naoee | aes | 03H = EOF, partial record 
| cs 
| le 
ed 
a ae 


DX must contain the offset (from the segment address in _ DS) 
of an opened FCB. The Current Block (offset OCH) and 
Current Record (offset 20H) fields are set to agree with the 
Relative Record field (offset 21H), then the record 
addressed by these fields is loaded at the Disk Transfer 
Address. 


AL returns a code that describes the processing: 


Code Meaning 
0 Read completed successfully. 
1 End-of-file; no data in the record. 
2 Not enough room at the Disk Transfer Address 


to read one record; read canceled. 


3 End-of-file; a partial record was read and 
padded to the record length with zeros. 


Macro Definition: read ran macro fcb 
mov dx,offset fcb 
mov ah,21H 
call loc_50H 
endm 7 
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Example 


The following program prompts for a letter, converts’ the 
letter to its alphabetic sequence (A = 1, B = 2, etc.), then 
reads and displays the corresponding record from ae file 
named ALPHABET.DAT on the disk in drive B. The file 


contains 26 records; each record is 28 bytes long. 
record size equ OEH ;offset of Record Size 
7 ;field of FCB 

relative record equ 21H ;offset of Relative Record 

: 7 field of FCB 

fcb db 2,""ALPHABETDAT" 
db 26 dup (?) 

buf fer db 28 4up(?7}),"Ss" 

prompt db "Enter letter: $* 

crlf db ODH,OAH,"S" 

begin: set dta buffer ;see Function 1AH 
open Ecb ;see Function OFH 
mov feb[record size],28 ;set record size 

get char: display prompt >see Function 09H 

> read kbd and echo >see Function 01H 
cmp s— ail, ODH ;just a CR? 
je all done ;yes, go home 
Sub al,41H sconvert ASCII code 
;to record # 
MOV fcb(relative record],al ;set relative 
;record 

display crlf ;see Function 09H 
read ran fcb ;THIS FUNCTION 
display buffer ;see Function 09H 
display crlf ;see Function 09H 
jmp get char ;get another char. 


all done: close fob. >see Function 10H 
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Random Write (Function 22H) 


os a a Call 
o [| a AH = 22H 
o [| a | DS : DX 
om [a Opened FCB 
a ae 
ioe ca Return 
ce seat AL 
a es OOH = Write completed successfully 
a 01H = Disk full 
Triaas~ | Faas: | 02H = DTA too small 
eee Saeae 
ee 
a 
a aes 


DX must contain the offset from the segment address in DS of 
an opened FCB. The Current Block (offset OCH) and Current 
Record (offset 20H) fields are set to agree with the 
Relative Record field (offset 21H), then the- record 
addressed by these fields is written from the Disk Transfer 
Address. If the Record Size is less than a sector, the data 
at the Disk Transfer Address is written to a buffer; the 
buffer is written to disk when it contains a full sector of 
data, or the file is closed, or a Reset Disk system call 
(Function ODH) is issued. 


AL returns a code that describes the processing: 


Code Meaning 
0 Write completed successfully. 
I Disk is full. 
2 Not enough room at the Disk Transfer Address 


to write one record; write canceled. 


Macro Definition: write ran macro fcb 
Mov dx,offset fcb 
mov ah,22H 
call loc 50H 
endm - 
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Example 


The following program prompts for a letter, converts’ the 
letter to its alphabetic sequence (A = 1, B = 2, etc.), then 
reads and displays the corresponding record from a file 
named ALPHABET.DAT on the disk in drive B. After displaying 
the record, it prompts the user to enter a changed record. 
If the user types a new record, it is written to the file; 
if the user just presses RETURN, the record is not replaced. 
The file contains 26 records; each record is 28 bytes long. 


record size equ OEH ;offset of Record Size 
_ ;field of FCB 
relative record equ 21H ;offset of Relative Record 
: = field of FCB 
fcb db 2," ALPHABETDAT" 
db 26 dup (7?) 
buf fer db 28 dup(?),0DH,0AH,"$" 
prompt] db "Enter letter: $”* 
prompt2 db "New record (RETURN for no change): $" 
erle db ODH,OAH,"$" 
reply db 28 dup (32) 
blanks db 26 dup (32) 
begin: set dta buffer ;see Function 1AH 
open Fob ;see Function OFH 
mov fecb[record size],28 ;set record size 
get char: display promptl ;see Function 09H 
read kbd and _echo ;see Function 01H 
cmp al,ODH ;just a CR? 
je all done ;yes, go home 
sub al,4LA sconvert ASCII 
7;code to record # 
mov fecb[relative record],al 
= ;set relative record 
display crlf ;see Function 09H 
read ran fcb ;THIS FUNCTION 
display buffer ;see Function 09H 
display crlf ;see Function 09H 
display prompt2 ;see Function 09H 
get string 27,reply ;see Function OAH 
display crlf ;see Function 09H 
cmp reply[1],0 ;was anything typed 
sbesides CR? 
je get char ;no 
a ;get another char. 
xOr bx,bx ;to load a byte 
mov bl,reply[1] ;use reply length as 
;counter 


move string blanks,buffer,26 ;see chapter end 

move string reply[2],buffer,bx ;see chapter end 

write ran fcb ;THIS FUNCTION 

jmp  — get_char ;get another character 
all done: close od 7see Function 10H 
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File Size (Function 23H) 


Call 
AH = 23H 
DS :DX 
Unopened FCB 


Return 

AL 
OOH Directory entry found 
FFH = No directory entry found 





DX must contain the offset (from the segment address in _ DS) 


of an unopened FCB. You must set the Record Size field 
(offset OEH) to the proper value before calling this 
function. The disk directory is searched for the first 


matching entry. 


If a matching directory entry is found, the Relative Record 
field (offset 21H) is set to the number of records in the 
file, calculated from the total file size in tthe directory 
entry (offset 1CH) and the Record Size field of the FCB 
(offset OEH). AL returns 00. 


If no matching directory is found, AL returns FFH. 


NOTE 


If the value of the Record 
Size field of the FCB (offset 
OEH) is not an even divisor of 
the file size, the value set 
in the relative record field 
is rounded up which yields a 
Size larger than the true file 
size. 
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Macro Definition: file size macro feb 


Mov dx,offset fcb 
MOV ah,23H 

int 21H 

endm 


Example 


The following program prompts for the name of a file, opens 
the file to fill in the Record Size field of the FCB, issues 
a File Size system call, and displays the file size _ and 
number of records in hexadecimal. 


fob db 37 dup (7?) 

prompt db "File name: $”" 

msg 1 db "Record length: ",0DH,0OAH,"$" 

msg 2 db "Records: ",ODH ,OAH,"$* 

erie db ODH,OAH,"S$" 

reply db 17 dup(?) 

sixteen db 10H 

begin: display prompt ;see Function 09H 
get string 17,reply ;see Function OAH 
cmp reply[l],0 ;just a CR? 
jne get length ;no, keep going 
jmp all done s;yes, go home 

get length: display crlf ;see Function 09H 
parse reply[2],fcb ;see Function 29H 
open Feb ;see Function OFH 
file size fcb ;THIS FUNCTION 
mov si,21H soffset to Relative 

;Record field 

MOv di,09H ;reply in msg 2 

convert it: cmp Fesiei] 0 sdigit to convert? 
je show it ;no, prepare message 
convert fcb[si],ten,msg 2[di] 
inc si ~ bump n-o-r index 
inc di ;bump message index 
jmp convert it check for a digit 

show it: convert fcb[0OEH],sixteen,msg 1[0FH] 

a display msgl >see Function 09H 

display msg2 ;see Function 09H 
jmp begin ;get a filename 


all done: close fcb >see Function 10H 
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Set Relative Record (Function 24H) 


Call 
AH = 24H 
DS :DX 
Opened FCB 


AX: 
BX: 
Cx: 
OX: 


Return 
None 





DX must contain the offset (from the segment address in DS) 
of an opened FCB. The Relative Record field (offset 21H) is 
set to the same file address as the Current Block (offset 
OCH) and Current Record (offset 20H) fields. 


Macro Definition: set relative record macro fcb 


mov dx,offset fcb 
mov ah,24H 

call loc 50H 

endm = 


Example 


The following program copies a file using the Random. Block 
Read and Random Block Write system calls. It speeds the 
copy by setting the record length equal to the file size and 
the record count to 1, and uSing a buffer of 32K bytes. It 
positions the file pointer by setting tthe Current Record 
field (offset 20H) to 1 and uSing Set Relative Record to 
make the Relative Record field (offset 21H) point to the 
same record as the combination of the Current Block (offset 
OCH) and Current Record (offset 20H) fields. 


current record equ 20H ;offset of Current Record 
;field of FCB 

file size equ 10H ;Ooliset of File Size 

; field of FCB 

fcb db 37 dup (?) 

filename db 17 dup(?) 

promptl db "File to copy: $" ;see Function 09H for 

prompt 2 db "Name of copy: $" ;explanation of §$ 

CrLe db ODH,O0AH,"S$" 

file length dw ? 


buffer db 32767 dup(?) 
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set dta buffer ;see Function 1AH 
display promptl ;see Function 09H 
get string 15,filename 7see Function OAH 
display crlf ;see Function 09H 
parse filename[2],fcb ;see Function 29H 
open fcb ;see Function OFH 
MOV feb[current record],0 ;set Current Record 
a sfield 

set relative record fcb ;THIS FUNCTION 
MOV ax,word ptr fcb[file size] ;get file size 
mov file length,ax *save it for 

= ;ran_block write 
ran block read fcb,1l,ax ;see Function 27H 
display prompt2 ;see Function 09H 
get string 15,filename ;see Function OAH 
display crlf ;see Function 09H 
parse filename[2],fcb >see Function 29H 
create fcb ;see Function 16H 
Mov fcb[current record],0 ;set Current Record 

Z sfield 
set relative record fcb >THIS FUNCTION 
MOV — ax,file length ;get original file 
7 ;length 

ran_ block write fcb,1l,ax :;see Function 28H 


close fcb >see Function 10H 
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Set Vector (Function 25H) 


Call 
AH = 25H 
AL 
Interrupt number 
DS :DX 


ae Interrupt-handling routine 
a wa Return 


> None 


AX: 
Bx 
Cx 


Ox 





Function 25H should be used to set a particular interrupt 
vector. The operating system can then manage the interrupts 
On a per-process basis. Note that programs should never set 
interrupt vectors by writing them directly in the low memory 
vector table. 





DX must contain the offset (to the segment address in DS) of 
an interrupt-handling routine. AL must contain the number 
of the interrupt handled by the routine. The address in the 
vector table for the specified interrupt is set to DS:DxX. 


Macro Definition: 
set vector macro interrupt,handler start 


MOv al,interrupt 
MOV dx,offset handler start 
mov ah,25H 
endm 
Example 
lds dx,intvector 
Mov ah, 25H 
Mov al,intnumber 
int 21H 


sThere are no errors returned 
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Random Block Read (Function 27H) 


Number of blocks read 


«fe px] Call 
mf fe] AH = 278 
eae ge eee 
ae Number of blocks to read 
te 
= as 
[ Return 
car nee a 
OOH = Read completed successfully 
| uaase | FLAGS. | 01H = EOF 
a 02H = End of segment 
a ae 03H = EOF, partial record 
rs 
Lee 


DX must contain the offset (to the segment address in DS) of 
an opened FCB. CX must contain the number of records to 
read; if it contains 0, the function returns’ without 
reading any records (no operation). The specified number of 
records -- calculated from the Record Size field (offset 
OEH) - is read starting at the record specified by the 
Relative Record field (offset 21H). The records are _ placed 
at the Disk Transfer Address. 


AL returns a code that describes the processing. 


Code Meaning 
0 Read completed successfully. 
i End-of-file; no data in the record. 
2 Not enough room at the Disk Transfer Address 


to read one record; read canceled. 


3 End-of-file; a partial record was read 
and padded to the record length with zeros. 


CX returns the number of records read, including the partial 
record if the AL code is 3; the Current Block (offset OCH), 
Current Record (offset 20H), and Relative Record (offset 
21H) fields are set to address the next record. 
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Macro Definition: 


Function 27H 


Page 1-87 


word ptr fcb[14],rec_size 


ran block read macro fcb,count,rec_size 
7 Mov dx,offset fcb 
Mov cx, count 
MOV 
mMOv ah,27H 
call loc 50H 
endm . 


Example 


The following program copies a file using the 


Read system call. 
using a 


specifies a 
the file size). 


Current record equ 20H ;offset of 
file size equ 10H ;offset of 
fcb db 37 dup (?) 
filename db 17 dup(?) 
promptl db "File to copy: $" 
prompt 2 db "Name of copy: $" 
erlet db ODH,OAH,"$" 
file length dw ? 
buffer db 32767 dup(?) 
begin: set dta buffer 
display promptl 
get string 15,filename 
display crlf 
parse filename[2],fcb 
open fcb 
mov 


feb[current record] ,0 


set relative record fcb 


size, 


Current Record field 
File Size field 


;see Function 09H for 
;explanation of $ 


1AH 
09H 
OAH 
09H 


Function 
Function 
Function 
Function 
Function 29H 
Function OFH 
sset Current 
sRecord field 


s:see Function 24H 


,;see 
,;see 
7see 
,;see 
,;see 
,;see 


ax, word ptr fcb[file size] 


Mov 

Mov file length,ax 
ran_ block read _ fcb,1,ax 
display prompt2 

get string 15,filename 
display crlf 

parse filename[2],fcb 
create fcb 

mov 


sget file size 
:save it 

:THIS FUNCTION 
:see Function 09H 
see Function OAH 
:see Function 09H 
:see Function 29H 
:see Function 16H 


feb[current_ record] ,0;set current 


set relative record fcb 


ran block write 


close 


fcob,l,ax 
fcb 


sRecord field 

>see Function 24H 
;see Function 28H 
ssee Function 10H 


Random Block 
It speeds the copy by specifying a record 
count of 1 and a record length equal to the file 
buffer of 32K bytes; 


and 
the file is read as a Single 
record (compare to the sample program for Function 28H that 


record length of 1 and a record count equal to 
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Random Block Write (Function 28H) 


«fm [x] Call 

BX. | BH | om AH = 28H 

a“ | om | a | DS : DX 

Dx. | om | ot Opened FCB 
X 


Number of blocks to write 
(0 = set File Size field) 


a as 
eS 
P| 
ae 

Return 
a ae AL 
| Fiacs. | FLaGs. 00H 
Te 01H 
ae sae 02H 
a ae 
a ee 


Write completed successfully 
Disk full 
End of segment 


CX 
Number of blocks written 


DX must contain the offset (to the segment address in DS) of 
an opened FCB; CX must contain either the number of records 
to write or 0. The specified number of records (calculated 
from the Record Size field, offset OEH) is written from the 
Disk Transfer Address. The records are written to the file 
Starting at the record specified in the Relative Record 
field (offset 21H) of the FCB. If CX is 0, no records’ are 
written, but the File Size field of the directory entry 
(offset 1CH) is set to the number of records specified by 
the Relative Record field of the FCB (offset 21H); 
allocation units are allocated or released, as required. 


AL returns a code that describes the processing: 


Code Meaning 
0 Write completed successfully. 
I Disk full. No records written. 
2 Not enough room at the Disk Transfer Address 


to read one record; read canceled. 


CX returns the number of records written; the current block 
(offset OCH), Current Record (offset 20H), and Relative 
Record (offset 21H) fields are set to address the next 
record. 
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Macro Definition: 
ran block write macro’ fcb,count,rec size 


mov dx,offset ficb 

mMOv cx,count 

MOv word ptr fcb[14],rec size 
mov ah, 28H 

call loc 50H 

endm - 


Example 


The following program copies a file using the Random Block 
Read and Random Block Write system calls. It speeds the 
copy by specifying a record count equal to the file size and 
a record length of 1, and using a buffer of 32K bytes; the 
file is copied quickly with one disk access each to read and 
write (compare to the sample program of Function 27H, that 
specifies a record count of 1 and a record length equal _ to 
file size). 


current record equ 20H ;offset of Current Record field 


file size equ 10H ;offset of File Size field 
fcb db 37 dup (?) 
filename db 17 dup(?) 
promptl db "File to copy: $" ;see Function 09H for 
prompt 2 db "Name of copy: $" ;explanation of $ 
crit db ODH,OAH,"$" 
num_recs dw ? 
buffer db 32767 dup(?) 
é 
begin: set dta buffer ;see Function lAH 
display promptl ;see Function 09H 
get_string 15,filename ;see Function OAH 
display crlf ;see Function 09H 
parse filename[2],fcb ;see Function 29H 
open fcb ;see Function OFH 
MOv feb[current_ record] ,0;set Current 
Record field 
set relative record fcb ;see Function 24H 
mov | ax, word ptr fcb[file size] 
7get file size 
mov num recs,ax ;save it 
ran_block_read fcb,num_recs,l1 ;THIS FUNCTION 
display prompt2 ;see Function 09H 
get string 15,filename ;see Function OAH 
display crlf ;see Function 09H 
parse filename[2],fcb ;see Function 29H 
create fcb ;see Function 16H 
MOV feb(current_record],0 ;set Current 
;Record field 
set relative record fcb see Function 24H 


ran block write fcb,num_recs,1l ;see Function 28H 
close fcb ;see Function 10H 
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Parse File Name (Function 29H) 


Call 
AH = 29H 
AL 
Controls parsing (see text) 
DS:SI 
String to parse 
ES :DI 
Unopened FCB 


AX: 
BX: 
Cx 


DX: 





aa 
a ane 
a 
Denar eae oe 
AL 
| FLAGSH FLAGS: OOH No wild card characters 
a ae 
ie ee 


O1H = Wild card characters used 
FFH = Drive letter invalid 
DS:S1 
First byte past string that was 
parsed 
ES: DI 


Unopened FCB 


SI must contain the offset (to the segment address in DS) of 


a String (command line) to parse; DI must contain the 
offset (to the segment address in ES) of an unopened FCB. 
The string is parsed for a filename of the form 


d:filename.ext; if one is found, a corresponding unopened 
FCB iS created at ES:DI. 


Bits 0-3 of AL control the parsing and processing. Bits 4-7 
must be set to 0. 


Bit Value Meaning 

0 0 All parsing stops if a file Separator is 
encountered. 

1 Leading separators are ignored. 

1 0 The drive number in the FCB is set to 0 
(default drive) if the string does not 
contain a drive number. 

1 The drive number in the FCB is not changed 
if the string does not contain a drive 
number. 

Z I The filename in the FCB is not changed if 


the string does not contain a filename. 


0 The filename in the FCB is set to 8 blanks 
if the string does not contain a filename. 
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3 1 The extension in the FCB is not changed 
if the string does not contain an extension. 


0 The extension in the FCB is set to 3 blanks 
if the string does not contain an extension. 


If the filename or extension includes an asterisk (*), all 
remaining characters in the name or extension are set to 
question mark ("?")., 


Filename separators: 
$s x y» = +7" € 1X <> | Space tab 


Filename terminators include all the filename separators 
plus any control character. A filename cannot contain a 
filename terminator; if one is encountered, parsing stops. 


If the string contains a valid filename: 


1. AL returns 1 if the filename or extension contains 
a wild card character ("*" or "?"); AL returns 0 
if neither the filename nor extension contains a 
wild card character. 


2. DS:SI point to the first character following’ the 
String that was parsed. 


ES:DI point to the first byte of the unopened FCB. 


If the drive letter is invalid, AL returns’ FFH. If the 
string does not contain a valid filename, ES:DI+l points to 
a blank (ASCII 32). 


Macro Definition: parse macro string,fcb 
Mov si,offset string 
Mov di,offset fcb 


push es 
push ds 
pop es 


MOV al,OFH ;bits 0, l, 2, 3 on 
MOv ah, 29H 
call loc_50H 


pop es 
endm 
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Example 


The following program verifies the existence of the file 
named in reply to the prompt. 


fcb db 37 dup (7) 

prompt db "Filename: $" 

reply db 17 dup(?) 

yes db “FILE EXISTS” ,ODH,0OAH,"*$” 

no db "FILE DOES NOT EXIST",ODH,0OAH,"S$" 

begin: display prompt ;see Function 09H 
get string 15,reply ;see Function OAH 
parse reply[2],fcb ;THIS FUNCTION 
search first fcb ;see Function 11H 
cp al,OFFH ;dir. entry found? 
je not there ;no 
display yes ;see Function 09H 


jmp return 
not there: display no 
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Get Date (Function 2AH) 


ro ee Call 
x [ox [a | AH = 2AH 
ox [om | oo | eheais 
CX 
Year (1980 - 2099) 
DH 
Month (1 - 12) 
DL 
Day {1 = 31) 
AL 


Day of week (0=Sun., 6=Sat.) 


This function returns the current date set in the operating 
system as binary numbers in CX and DX. 


CX Year (1980-2099) 

DH Month (1 = January, 2 = February, etc.) 

DL Day (1-31) 

AL Day of week (0 = Sunday, 1 = Monday, etc.) 


Macro Definition: get date macro 
ad Mov ah, 2AH 
call loc_50H 
endm 
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Example 


The following program gets the date, increments the day, 


increments the month or year, if necessary, and sets the new 
date. 


month db 31,728 ¢31,30¢31530431431;,30731,30;,31 
begin: get date ;see above 
inc dl ;increment day 
XO bx, bx ;Sso BL can be used as index 
mov b1l,dh ;move month to index register 
dec bx ;month table starts with 0 
cmp dl,month[bx] ;past end of month? 
jle month ok >no, set the new date 
mov aigt ;yes, set day to l 
inc dh ;and increment month 
cmp dh,12 ;past end of year? 
jle month ok sno, set the new date 
MOV an, 1 ;yes, set the month to 1 
inc Cx ;increment year 


month ok: set date cx,dh,dl *THIS FUNCTION 
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Set Date (Function 2BH) 


oe ce Call 
x [ew [oe | = AH = 28H 
Cx: 
Low | a Y = 
o: [| om | om | - ear (1980 2099) 
a ae Month (1 - 12) 
_ DL 
a ae Day (1 - 31) 
| mT 
ee Return 
Pass. | Fass. | — 
ma sae OOH = Date was valid 
ma See FFH = Date was invalid 
ae Sa 
pM 


Registers CX and DX must contain a valid date in binary: 


CX Year (1980-2099) 
DH Month (1 = January, 2 = February, etc.) 
DL Day (1-31) 


If the date is valid, the date is set and AL returns 0. If 
the date is not valid, the function is canceled and AL 
returns FFH. 


Macro Definition: set date macro year,month,day 


mov cx,year 
mov dh,month 
mov dl,day 
mov ah, 2BH 


call loc_50H 
endm 
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Example 


The following program gets the date, increments the day, 
increments the month or year, if necessary, and sets the new 
date. 


month db 3172057 31,30;,31,30;,31, 31; 30731,30,31 
begin: get date ;see Function 2AH 
inc dl ;increment day 
xOr bx, bx >So BL can be used as index 
mov bl,dh smove month to index register 
dec bx smonth table starts with 0 
cmp dl,month[bx] ;past end of month? 
jle month ok ;no, set the new date 
mov ai. 1 syes, set day to l 
inc dh sand increment month 
cmp dh,12 ;past end of year? 
jle month ok sno, set the new date 
MOV dh,l | syes, set the month to 1 
inc cx ;increment year 


month ok: set date cx,dh,dl ;THIS FUNCTION 
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Get Time (Function 2CH) 


Pe es a Call 
ex | eH | a | AH = 2CH 
Return 
a ee CH 
a ae Hour (0 - 23) 
ae CL 
as Minutes (0 - 59) 
| un 
aaa | aa | Pees (0 59) 
Hundredths (0 - 99) 
a ae 
| 
a 7s 


This function returns the current time set in the operating 
system as binary numbers in CX and DX. 


CH Hour (0-23) 

CL Minutes (0-59) 

DH Seconds (0-59) 

DL Hundredths of a second (0-99) 


Macro Definition: get time macro 
- mov ah, 2CH 
call loc_50H 
endm 


Example 


The following program continuously displays the time until 
any key is pressed. 


time db "00:00:00.00",0DH,"$" 

ten db OAH 

begin: get time ;THIS FUNCTION 
convert ch,ten,time ;see end of chapter 


convert cl,ten,time[3] ;see end of chapter 
convert dh,ten,time[6] ;see end of chapter 
convert dl,ten,time[9] ;see end of chapter 


display time ;see Function 09H 

check _kbd status ;see Function OBH 

cmp al,OFFH ;has a key been pressed? 
je return ;yes, terminate 


jmp begin ;no, display time 
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Set Time (Function 2DH) 


«fe Te] Call 

ox | eo | a | AH = 2DH 

a [oe [a _ CH 

ox: [oom | oo Hour (0 - 23) 

CL 

a ae Minutes (0 - 59) 
| DH 
as Seconds (0 - 59) 
ae ae DL 
ae saa Hundredths (0 - 99) 
[ Fuacs» | FLAGS: | 
[Ts] —séReturn 
AL 
Toss Cd OOH = Time was valid 
a ee 


FFH = Time was invalid 


Registers CX and DX must contain a valid time in binary. 


CH Hour (0-23) 

CL Minutes (0-59) 

DH Seconds (0-59) 

DL Hundredths of a second (0-99) 


If the time is valid, the time is set and AL returns 0. Tf 
the time is not valid, the function is canceled and AL 
returns FFH. 


Macro Definition: 
set time macro  hour,minutes,seconds,hundredths 


mov ch, hour 

mov cl,minutes 
mov dh,seconds 
mov dl,hundredths 
mov ah, 2DH 


call loc_50H 
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Example 


The following program sets the system clock to 0 and 
continuously displays the time. When a character is typed, 
the display freezes; when another character is typed, the 
clock is reset to 0 and the display starts again. 


time ab "00:00:00.00",0DH,0AH,"S”"* 

ten db 10 

begin: set_time 0,0,0,0 ;THIS FUNCTION 

read clock: get time ;see Function 2CH 
convert ch,ten,time ;see end of chapter 


convert cl,ten,time[3] ;see end of chapter 
convert dh,ten,time[6] ;see end of chapter 
convert dl,ten,time[9] ;see end of chapter 


display time ;see Function 09H 
dir console io OFFH ;see Function 06H 
cmp al,00H ;was a char. typed? 
jne stop ;yes, stop the timer 
jmp read clock ;no keep timer on 
stop: read kbd a >see Function 08H 


jmp begin ;keep displaying time 
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Set/Reset Verify Flag (Function 2EH) 


Bx: AH = 2EH 
Cx: AL 
Ox: OOH = Do not verify 
OlH = Verify 
Return 
None 


AL must be either 1 (verify after each disk write) or 0 
(write without verifying). MS-DOS checks this flag each 
time it writes to a disk. 


The flag is normally off; you may wish to turn it on when 
writing critical data to disk. Because disk errors are rare 
and verification slows writing, you will probably want to 
leave it off at other times. 


Macro Definition: verify macro switch 
mov al,switch 
MOV ah, 2EH 
call loc_50H 
endm 


SYSTEM CALLS 


Example 


The following program copies the contents of a 
drive 


disk 
write. 


on 
of f 


prompt 


first 
buffer 


begin: 


Copy: 


equ 
equ 


db 
db 
dw 
db 


Function 2EH 


to the 


L 
0 
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single-sided 


disk in drive B, verifying each 
It uses a buffer of 32K bytes. 


"Source in A, target in B",0DH,OAH 


"Any key to start. $" 
0 
60 dup (512 dup(?)) 


display prompt 
read_kbd 
verify on 


mOv 
push 


abs disk read 
abs disk write 


add 


pop 
loop 


ox,6 
Cx 


Start,60 
cx 


COpy 


verify off 


:60 sectors 


;see Function 09H 
>see Function 08H 
;THIS FUNCTION 
scopy 60 sectors 
;Save counter 


0,buffer,60,first ;see Int 25H 
1,buffer,64,first ;see Int 26H 


:do next 60 sectors 
s;restore counter 
;do it again 

>THIS FUNCTION 
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Get DTA (Function 2FH) 


Call 
AH = 2FH 


AX: 
Bx: 
Cx: 
Return 
ES :BX 


Dx: 
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Points to Disk Transfer Address 


ES returns the segment address of the current Disk Transfer 
Address; BX returns the offset. 
Macro Definition: get dta macro 
mov ah,2fH 
call loc_50H 
endm 
Example 
The following program displays the current Disk Transfer 
Address in the form segment:offset. 
message db "DTA oe ° ",0DH,OAH,"S$" 
sixteen db 10H 
temp db 2 dup (?) 
begin: get _dta ;THIS FUNCTION 
Mov word ptr temp,ex ;TO access each byte 
convert temp[1],sixteen,message [07H] >See end of 
convert temp,sixteen,message [09H] ;chapter for 
convert bh,sixteen,message [0CH] ;description 
convert bl,sixteen,message [0EH] sof CONVERT 


display message ;See Function 09H 
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Get DOS Version Number (Function 30H) 


«fe [ex] call 
« [mw [= | AH = 30H 
» [Tm [a] Return 
a ae Major version number 
2 oe AH 
aa See Minor version number 
a ee BH 
ar aes OEM serial number 
BL:CX 
| Fuacs | Fiacs: | 24-bit user (serial) number 
PS 
| os 
pS 
pS 


AL returns the major version number; AH returns the = minor 
version number. (For example, MS-DOS 2.01 returns 2 in AL 
and 1 in AH. 

If AL returns 0, the version of MS-DOS is earlier than 1.28. 


Macro Definition: get version macro 


mov ah, 30H 
call loc_50H 
endm 


Example 


The following program displays the version of MS-DOS if it 
is 1.28 or greater. 


message db "MS-DOS Version “ ODH ,OAH, "S$" 

ten db OAH >For CONVERT 

begin: get_version ;THIS FUNCTION 
cmp al,0 21.28 or later? 
jng return >No, go home 
convert al,ten,message [0FH] ;See end of chapter 
convert ah,ten,message [12H] for description 


display message ;See Function 9 
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Terminate but Stay Resident (Function 31h) 


Call 
AH = 31H 
AL 
Exit code 
DX 
Memory size, in paragraphs 


Return 
None 


DX must contain the amount of memory required by the 
program, in paragraphs (one paragraph = 16 bytes). AL 
contains an exit code. 


The current process is terminated and MS-DOS tries to. set 
the initial allocation block to the number of paragraphs in 
DX. No other allocation blocks belonging to the process are 
released. 


The exit code in AL can be retrieved by the parent process 
with the Wait system call (Function 4DH) and can be tested 
with the error level batch command. 


This Function Request allows more than 64K bytes to remain 
resident; you should use it, rather than Terminate But Stay 
Resident (Interrupt 27H), unless your program must be 
compatible with earlier versions of MS-DOS. This call does 
not require CS:0 to point to your PSP like INT 27H. 


No macro definition or example is included for Function 31H. 
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CONTROL-C Check (Function 33H) 


ax [oa | a Call 
x {oe | a AH = 33H 
ox AL 
ox [ on | om Function 
ae OOH = Request current state 
a O1H = Set state 
a Sa DL (if setting) 
eae a Se ee 
O1H = On 
a aaa 
FLAGSx Return 
DL 
OOH = Off 
a O1H = On 
bo 
a ae 


AL must contain a code that specifies the requested action: 


0 Return current state of CONTROL-C checking. 
1 Set state of CONTROL-C checking. 


If AL is l, the value in DL specifies the state to be set (0 
= off, 1 = on). If AL is 0, DL returns a code that 
specifies the current state (0 = off, 1 = On). 


If the code in AL is neither O nor 1, AL returns FFH and the 
state of CONTROL-C checking is not affected. 


MS-DOS normally checks for CONTROL-C on the controlling 
device only when performing certain function requests in the 
01H through OCH group. (See specific calls for details). 
This function request expands CONTROL-C checking to include 
any function request. For example, with CONTROL-C- checking 
off, all disk I/O proceeds without interruption; with 
CONTROL-C checking on, the CONTROL-C interrupt is given at 
the function request that initiates the disk operation. 


NOTE 


Programs that use Function 
Request 06H or 07H to read 
CONTROL-C as data musSt' ensure 
that the CONTROL-C checking is 
off. 
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Macro Definition: ctrl_c ck 


Example 


macro 
mov 
Mov 
MOV 
call 
endm 


action,state 
al,action 
dl,state 

ah, 33H 
loc_50H 


Page 1-106 


The following program displays a message that tells whether 
CONTROL-C checking is on or off: 


message db "CONTROL-C checking ","$" 

on db *on”, "S$" ,QDH, OAH, "5" 

of f db "OEL" "9", ODN, OAH, "S$" 

begin: display message ;See Function 09H 
ctrl c ck 0O ;THIS FUNCTION 
cmp  41l,o ;Is checking off? 
jg ck on ;NO 
display off ;See Function 09H 
jmp return ;Go home 

ck_on: display on 


>See Function 09H 
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Get Vector (Function 35H) 


« Te Ta Call 
ox [ow [| = ae 
ox: [ of | o | Interrupt number 
aa Return 
Pr ES :BX 
Le Pointer to interrupt routine 
eae 
Re ae 
jp Fuacs. | Acs. 
a ae 
os 
8s 
Le 


AL must contain the number of an interrupt. 


ES returns the segment address of the interrupt handler; BX 
returns the offset. 


Your program must use this’ function request, rather’ than 
reading the address directly from the vector table, if the 
MS-DOS version is 2.00 or greater. If your program must _ be 
compatible with earlier versions of MS-DOS, use Function 
Request 30H (Get DOS Version) to determine which version (of 
MS-DOS is running to choose the correct method. 


Macro Definition: get vector macro interrupt 
Mov al,interrupt 
MOv ah,35H 
call loc 50H 
endm 7 
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Example 


The following program displays the Segment:Offset (CS:IP) 
for the handler for Interrupt 25H (Absolute Disk Read). 


message db "Interrupt 25H -~- CS:0000 IP:0000" 
db ODH,0OAH,"$" 

sixteen db 10H 

vec_ seg db 2 dup (?) 

vec off db 2 dup (?) 

begin: get_vector 25H ;THIS FUNCTION 
mov word ptr vec_seg,es ;TO access each byte 
MOV word ptr vec _off,bx 7TO access each byte 


> SEE END OF CHAPTER FOR DESCRIPTION OF CONVERT MACRO 
convert vec seg[1l],sixteen,message [14h] 
convert vec _seg,sixteen,message [16h] 
convert vec off[1l],sixteen,message[1Ch] 
convert vec off,sixteen,message[1lEh] 
display message ;See Function 9 
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Get Disk Free Space (Function 36H) 


Call 

AH = 36H 

DL 
Drive (0 = default, 
1 =A, etc.) 


AX 
BX: 
Cx: 
OX: 


Return 
AX 
FFFF if drive number is invalid; 
otherwise sectors per cluster 
BX 
Available clusters 
CX 
Bytes per sector 
DX 
Clusters per drive 


INH 
LL UEPE 


DL must contain a drive number 
(0 = default, 1 = A, etc.). 


If the drive number is valid, the information is returned in 
the following registers: 


AX Sectors per cluster 
BX Available clusters 
CX Bytes per sector 

DX Total clusters 


If the drive number is invalid, AX returns FFFFH. 


This call supersedes Function Requests 1BH and 1CH in 
earlier versions of MS-DOS. 


Macro Definition: get disk space macro drive 
on = mov dl,drive 
Mov ah,36H 
call loc_50H 
endm 
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Example 


The following program displays (in hexadecimal) the number 
of bytes available on the disk in drive B. 


message db & dup (" 7) ,*8-* 
db "bytes available on drive B",0DH,0OAH,"S$" 
sixteen db 10H 
begin: get disk space 2 ;THIS FUNCTION 
cnp ax,ffffh sEXKrOr? 
je error bad drive ;ROoutine not shown 
mul cx ;Sectors per cluster * bytes per sector 
mul bx ;Bytes per cluster * available clusters 
convert dh,sixteen,messagel See end of 


convert dl,sixteen,messagel[02H] ; chapter for 
convert ah,sixteen,messagel[04H] ; descrivtion of 
convert al,sixteen,messagel[{06H] ; CONVERT macro 
display message ;See Function 09H 
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Get Country Data (Function 38H) 


Call 
AH = 38H 
DS : DX 
Pointer to 32-byte memory area or 
MX=-] to Set Current Country 
AL 
Country code. In MS-DOS 2.0, 
must be 0. 


AX: 
BX: 
Cx: 
Ox: 


Return 

Carry set: 

AX 
2 = File not found 

Carry not set: 

DS :DX 
Pointer to memory area filled with 
country data 


TINIE 
LLU EEE 


DX must contain either the offset (from the segment address 
in DS) of a 32-byte memory area in which the country data is 
to be returned, or -l1 to set the country code. AL must 
contain either a country code or 0 (for current country). 
The country code is usually the international telephone 
prefix code. 


The following table shows the format of the data returned in 
the memory area. 


Offset 
Field Bytes Hex Decimal 
Date and time format 2 (word) 00 0 
Currency symbol 5 (ASCIZ string) 02 2 
Thousands separator 2 (ASCIZ string) 07 7 
Decimal separator 2 (ASCIZ string) 09 9 
Date separator 2 (ASCIZ string) OB id 
Time separator 2 (ASCIZ string) OD i3 
Bit field 1 OF i 
Currency places 1 10 16 
Time format 1 ll m, 
Case-mapping cell 4 (dword) 12 18 
Data-list separator 2 (ASCIZ string) 16 22 
Most entries are formatted as an ASCIZ_ string (ASCII 


characters terminated by a byte of 00H), but a fixed size is 
allocated for each field for easy indexing into the table. 
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Date and Time Format: USA (h:em:s m/d/y) 
Europe (h:m:s d/m/y) 


Japan (h:m:s_ d/m/y) 


0 
L 
a 


Bit Field: Bit l 


QO No space between symbol and amount 
l1 Space between symbol and amount 


Bit 0 


0 Currency symbol precedes amount 
1 Currency symbol follows amount 


All other bits are undefined, 


12-hour time 
24-hour time 


Time format: 0 
1 


Currency Places: Specifies the number of places that appear 
after the decimal point on currency amounts. 


Case-Mapping Call: The segment and offset of a FAR 
procedure that performs country-specific lowercase-to- 
uppercase mapping on character values from 80H to OFFH. You 
call it with the character to be mapped in AL. If there is 
an uppercase code for the character, it iS returned in AL; 
if there is not, or if you call it with a value less than 
80H in AL, AL is returned unchanged. AL and the FLAGS are 
the only registers altered. 


If there is an error, the carry flag (CF) is set and _ the 
error code is returned in AX: 


Code Meaning 


Z Invalid country code (no table for it) 


NOTE 


This call is fully implemented 
in MS-DOS 2.01 and higher 
versions. It exists in 
version 2.00, but is not fully 
implemented. 


Macro Definition: get country macro mem area,action 


mov dx,offset mem area 
mov al,action 
mov ah,38H 


call loc_50H 
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Example 


The following program displays the time and date in the 
format appropriate to the current country code, and the 
number 999,999 and 99/100 aS a currency amount with the 
proper currency symbol and separators. 


time db " ¢ § *,5 dup (208) ,"3" 

date db = f / *,5 dup (208) ,*s" 

number db "999?999?99",0DH,0AH,"S$" 

ten db OAH 

data_area db 32 dup (?) 

begin: get_country data area,0 >THIS FUNCTION 
get time ;See Function 2CH 
convert ch,ten,time >See end of chapter 
convert cl,ten,time[03H] :;for description of 
convert dh,ten,time[06H] s;CONVERT macro 
get date >See Function 2AH 
sub — cx,1900 ;Want last 2 digits 
convert cl,ten,date[06H] >See end of chapter 
cmp word ptr data area,0 ;Check country code 
jne not_usa = ;It's not USA 
convert dh,ten,date >See end of chapter 
convert dl,ten,date[03H] See end of chapter 
jmp all done ;Display data 

not_usa: convert dl,ten,date >See end of chapter 
convert dh,ten,date[03H] :;See end of chapter 

all done: mov al,data_area[04H] >Thousand separator 
MOV number [03H] ,al Put in NUMBER 
MOV al,data_area[06H] >Decimal separator 
mov number [07H] ,al ;Put in AMOUNT 
display time ;See Function 09H 
display date ;See Function 09H 


display char data_area[02H] 7See Function 02H 
display number ;See Function 09H 
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Create Directory (Function 398) 


Bx: AH = 39H 
Cx: DS : DX 


Pointer to pathname 


Return 
Carry set: 
AX 
3 = Path not found 


5 = Access denied 
Carry not set: 
No error 


DX must contain the offset (from the segment address in DS) 
of an ASCIZ string that specifies the pathname of a new 


subdirectory. 


If the name is valid, a new directory is created. 


If there is an error, the carry flag (CF) is set and_ the 
error code is returned in AX. 


Code Meaning 
3 Path not found 
= No room in the parent directory; a file with the 


Same name exists in the current directory; or 
the path specifies a device 


Macro Definition: make dir macro path 
MOv dx,offset path 
MOv ah,39H 
call loc 50H 
endm 
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Example 


The following program adds a Subdirectory named NEWDIR_ to 
the root directory on the disk in drive B, changes the 
current directory to NEWDIR, changes the current directory 
back to the original directory, then deletes NEWDIR. It 


displays the current directory after each step to confirm 
the changes. 


Old path db "“bs\",0,63 @dup (7) 

new path db "b:\new_dir",0 

buffer db "b:\\*,0,63 dup (?) 

begin: get dir 2,0ld path[03H] >See Function 47H 
jc error get ;Routine not shown 
display asciz old path >See end of chapter 
make dir new path ;THIS FUNCTION 
Jc error make ;Routine not shown 
Change dir new_path ;See Function 3BH 
4c error change ;Routine not shown 
get dir 2,buffer [03H] :;See Function 47H 
je error get >Routine not shown 
display asciz buffer >See end of chapter 
change dir old path ;See Function 3BH 
je a error change ;Routine not shown 
rem dir new path >See Function 3AH 
jc error rem ;Routine not shown 
get dir 2,buffer [03H] >See Function 47H 
je error get ;Routine not shown 


display asciz buffer >See end of chapter 


SYSTEM CALLS Function3AH Page 1-116 


Remove Directory (Function 3AH) 


« Tm TA Call 
ox [em [x | AH = 3aH 
x [re [oa | = BS:Dx. 
ox: [om | oo | Pointer to pathname 
a 7 Return 
| Carry set: 
a ee AX 
fl 3 = Path not found 
ar Sas 5 = Access denied 
16 = Current director 
ee | ae | Carry not set: . 
Ts No error 
| 
| 
hee ee 


DX must contain the offset (from the segment address in DS) 
of an ASCIZ string that specifies the pathname of the 
directory to be erased. 


If the name is a valid directory, and the directory is empty 
except for the "." and ".." entries, the directory is 
erased. 


You cannot erase the current directory. If there is an 
error, the carry flag (CF) is set and the error code is 
returned in AX. 


Code Meaning 
3 Path not found 
5 The directory isn't empty; or the path doesn't 


specify a directory, specifies the root 
directory, or is invalid 


16 Attempt to remove the current directory 
Macro Definition: rem_dir macro path 
mov dx,offset path 
mov ah, 3AH 


call loc_50H 
endm 
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Example 


The following program adds a Subdirectory named NEWDIR- to 
the root directory on the disk in drive B, changes the 
current directory to NEWDIR, changes the current directory 
back to the original directory, then deletes NEWDIR. It 


displays the current directory after each step to confirm 
the changes. 


Old path db “Bz \",0,.62 dup (2) 

new path db "b:\new_dir",0 

buffer db *"be\",0,63 dup (?) 

begin: get dir 2,0ld path[03H] -See Function 47H 
je error get ;ROutine not shown 
display _asciz old path ;See end of chapter 
make dir new path 7See Function 39H 
jc error make >ROutine not shown 
change dir new path ;See Function 3BH 
jc error change ;Routine not shown 
get dir 2,buffer [03H] >See Function 47H 
jc error get ;Routine not shown 
display asciz buffer ;See end of chapter 
change dir old path ;See Function 3BH 
je error change >Routine not shown 
rem dir new path ;THIS FUNCTION 
jc error rem ;Routine not shown 
get dir 2,buffer [03H] >See Function 47H 
ic error get >Routine not shown 


display asciz buffer :See end of chapter 
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Change Current Directory (Function 3BBH) 


Call 
AH = 3BH 
DS : DX 
Pointer to pathname 


AX: 
Bx: 
Cx: 
DX: 


Return 
Carry set: 
AX 
3 = Path not found 
Carry not set: 
No error 


DX must contain the offset (from the segment address in DS) 
of an ASCIZ string that specifies the pathname of a sub- 
directory. 


If the name is valid, the current directory is changed to 
the specified subdirectory. 


If any member of the path doesn't exist, the path is not 
changed. If there is an error, the carry flag (CF) is set 
and the error code is returned in AX: 


Code Meaning 
3 The path specifies either a file (not a 
directory) or an invalid path 


Macro Definition: change dir macro path 
= mov dx,offset path 
Mov ah, 3BH 
call loc_50H 
endm 
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Example 


The following program adds a subdirectory named NEWDIR_ to 
thé root directory on the disk in drive B, changes the 
current directory to NEWDIR, changes the current directory 
back to the original directory, then deletes NEWDIR. It 
displays the current directory after each step to confirm 
the changes. 


Old path db "be\",0,63 dup (7?) 

new path db "b:\new_dir",0 

buffer db “bs\",0,63 dup (7) 

begin: get dir 2,0ld_ path[03H]) :;See Function 47H 
jc error get ;Routine not shown 
display asciz old path ;See end of chapter 
make dir new path >See Function 39H 
a error make ;Routine not shown 
change dir new path ;THIS FUNCTION 
Jc error change ;ROutine not shown 
get dir 2,buffer [03H] >See Function 47H 
je error get ;Routine not shown 
display asciz buffer ;See end of chapter 
change dir old path ;See Function 3BH 
jc error change ;ROoutine not shown 
rem dir new path :;See Function 3AH 
je error rem ;Routine not shown 
get dir 2,buffer [03H] ;See Function 47H 
je error get ;Routine not shown 


display asciz buffer ;See end of chapter 
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Create Handle (Function 3CH) 


« [ow T «| Call 
«x | » [| «| AH = 3CH 
x [aw | =| DS : DX | 
ox: | of | mo Pointer to pathname 
CX 
Le File attribute 
Pr 
a a Return 
= as Carry set: 
ean = 
3 = Path not found 
[L ruacs» | mage | 4 = Too many open files 
a 5 = Access denied 
| Carry not set: 
pS ia 
ee ae 


DX must contain the offset (from the segment address in DS) 
of an ASCIZ string that specifies the pathname of the file 
to be created. CX must contain the attribute assigned to 
the file, as described in Table 1.6. 


If the specified file does not exist, it is created; if the 
file does exist, it is truncated to a length of 0. The 
attribute in CX is assigned to the file and the file is 
opened for read/write. AX returns the file handle. 


If there is an error, the carry flag (CF) is set and the 
error code is returned in AX. 


Code Meaning 
3 The path is invalid 
4 Too many open files (no handle available) 
a Directory full; a directory with the same name 


exists; or a file with the same name exists 
with more inclusive attributes 


Macro Definition: create handle macro path,attrib 


Mov dx,offset path 
mov cx,attrib 
mov ah, 3CH 


call loc_50H 
endm 
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Example 


The following program creates a file named DIR.TMP on the 
disk in drive B that contains the name and extension of each 
file in the current directory. 


srch file 
tmp file 
buffer 
handle 


begin: 


write it: 


all done: 


db “p:*,**7,,0 

db “bsdir.tmp* ,0 

db 43 dup (?) 

dw ? 

set dta buffer ;See Function 1AH 
find first file srch_file,16H ;See Function 4EH 
cmp ax,12H ;Directory empty? 
je all done ;Yes, go home 
create handle tmp file,0O >THIS FUNCTION 

je ~ error a >Routine not shown 
mov handle,ax Save handle 

write handle handle,buffer[1lEH],12 ;Function 40H 
find next file ;See Function 4FH 
cmp ax,12H ;Another entry? 

je all done ;No, go home 

jmp write it -Yes, write record 


close handle handle ;See Function 3EH 
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Open Handle (Function 3DH) 


AX: Call 
BX: AH = 3DH 
cx: AL = Access code 
Dx: 0 = Read 
l = Write 
2 = Both read and write 
DS : DX 
Pointer to pathname 
Return 
Carry set: 
AX 
2 = File not found 
4 = Too many open files 
5 = Access denied 
12 = Invalid access 





Carry not set: 
AX 
Handle 


DX must contain the offset (from the segment address in DS) 


of an ASCIZ string that specifies the pathname of the file 
to be opened. AL must contain the access code: 


Code Meaning 

OOH Read 

01H Write 

02H Read and write 


AX returns the file handle and the read/write pointer is set 
to the first byte. 


If there is an error, the carry flag (CF) is set and_ the 
error code is returned in AX. 


Code Meaning 


2 File not found 

4 Too many open files (no handle available) 

5 Path specifies a volume-id, directory, or 
read-only file 


l AL is not OOH, O1H, or 02H 


Nh 


The read/write pointer can be changed with Function Request 
42H (Move Pointer). The file's date and time can be 
obtained or set with Function Request 57H (Get/Set Date and 
Time). The file's attribute can be obtained or changed with 
Function Request 43 (Change Mode). 
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Macro Definition: open handle macro path,access 


mMOv dx,offset path 
MOV al,access 

MOv ah, 3DH 

call loc 50H 

endm 7 


Example 


The following program prints the file named TEXTFILE.ASC_ on 
the disk in drive B. 


file db "“b:textfile.asc",0 

buffer db ? 

handle dw ? 

begin: open handle file,0O ;THIS FUNCTION 
mov handle,ax s>Save handle 

read char: read handle handle,buffer,l ;Read 1 character 

a jc error read >Routine not shown 

cmp ax,0 ;End of file? 
je return 7Yes, go home 
print char buffer ;See Function 05H 


jmp read char ;Read another 
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Close Pile Handle (Function 3EH) 


Call 
AH = 3EH 
BX 
File handle 


AX: 
BX: 
Cx: 
OX: 


Return 
Carry set: 
AX 
6 = Invalid handle 
Carry not set: 
No error 





BX must contain the handle of an open file. 


The file is closed and all internal buffers are flushed. 


If there is an error, the carry flag (CF) iS set and _ the 
error code is returned in AX: 


Code Meaning 
6 Handle is not open or is invalid 


Macro Definition: close handle macro handle 
a Mov bx,handle 
mov ah,3EH 
call loc_50H 
endm 


SYSTEM CALLS Function 


Example 


The following program creates 
disk in drive B that contains 


file in the current directory. 


srch file db "“b:*.*",0 
tmp file db "b:dir.tmp",0 
buffer db 43 dup (?) 
handle dw ? 
begin: set dta buffer 
find first file 
cmp ax, 12H 
je all done 
create handle 
jc érror create 
MOV handle,ax 


write it: write handle 


srch_ file,16H 


tmp file,0O 


handle,buffer [1EH] 
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a file named DIR.TMP on the 
the name and extension of each 


>See Function 1AH 
>See Function 4EH 
;Directory empty? 
-Yes, go home 

>See Function 3CH 
sROutine not shown 
Save handle 

>See Function 


jc error write 7 40H 
find next file ;See Function 4FH 
cmp ax,12H ;Another entry? 
je all done ;No, go home 
jmp write it :Yes, write record 
all done: close handle handle >See Function 3EH 
7 jc — errror_close ;Routine not shown 
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Read File or Device (Function 3FH) 


5 = Access denied 
6 = Invalid handle 
Carry not set: 
AX 
Bytes read 


oe Call 
x [| = | AH = 3FH 
x [o | a BX 
ox | on | om | Handle 
om 
ae ee Bytes to read 
| DS : DX 
ft Pointer to buffer 
Ol 
a I ey 
[roc Trme] Carry set: 
eat ae 
| os 
ea ae 
| es 


BX must contain the file handle. CX must contain the number 
of bytes to be read. DX must contain the offset (to the 
segment address in DS) of the buffer. 


AX returns the number of bytes read if carry is not set; if 
you attempt to read starting at end of file, AX returns 0. 
The number of bytes specified in CX iS not necessarily 
transferred to the buffer; if you use this call to read 
from the keyboard, for example, it reads only up to the 
first CR. 


If you use this Function Request to read from_ standard 
input, the input can be redirected. 


If there is an error, the carry flag (CF) is set and the 
error code is returned in AX. 


Code Meaning 
5 Handle is not open for reading 
6 Handle is not open or is invalid 


Macro Definition: read handle macro handle,buffer,bytes 


Mov bx,cs:handle 

mov dx,offset buffer 
mov cx,cS:bytes 

MOV ah,3FH 


call cs:loc_50H 
endm 
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Example 


The following program displays the file named TEXTFILE.ASC 
on the disk in drive B. 


filename db "b:\textfile.asc",0 

buffer db 129 dup (?) 

handle dw Ks 

‘ 

begin: open handle filename,0 ;See Function 3DH 
jc error open ;ROoutine not shown 
Mov handle,ax Save handle 

read file: read handle buffer,file handle,128 
je error open ;Routine not shown 
cmp ax,0 sEnd of file? 
je return 7Yes, go home 
mov bx ,ax 7# of bytes read 
mov buffer [bx] ,"$" sMake a String 
display buffer >See Function 09H 


jmp read file ;Read more 
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Write File or Device (Function 40H) 


Call 
AH = 40H 
BX 
Handle 
Cx 
Bytes to write 
DS :DX 
Pointer to buffer 


AX: 
BX: 
CX. 
OX: 


Return 
Carry set: 
AX 
c 5 = Access denied 
6 = Invalid handle 


Carry not set: 
AX 
Bytes written 


BX must contain the file handle. CX must contain the number 
of bytes to be written. DX must contain the offset (to the 
segment address in DS) of the data to be written. 


AX returns the number of bytes written if carry iS not’ set. 
If this value is not the same as you specified in CX, it may 
indicate an error even though the carry flag isn't set; the 
most likely reason is a full disk. 


If you use this call to write to standard output, the output 
can be redirected. If you call with CX = 0, the file size 
is set to the value of the read/write pointer. 


If there is an error, the carry flag (CF) is set and_ the 
error code is returned in AX. 


Code Meaning 
5 Handle is not open for writing 
6 Handle is not open or is invalid 


Macro Definition: write file macro handle,data,bytes 


Mov bx,handle 

MOV dx,offset data 
MOV cx,bytes 

mov ah,40H 


call loc 50H 
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Example 


The following program creates a file named DIR.TMP in the 
current directory on the disk in drive B that contains the 
filename and extension of each file in the current 
directory. 


Ssrch file db "bs? 3" ,0 

tmp file db “biair. timp” ,0 

buffer db 43 dup (?) 

handle dw 4 

begin: set dta buffer >See Function lAH 
find first file srch file,16H ;Check directory 
cmp ax, 12H ;Directory empty? 
je return ;Yes, go home 
create handle tmp file,0 ;See Function 3CH 
jc error create ;Routine not shown 
MOV handle,ax >Save handle 

write it: write handle handle,buffer[1lEH],12 ;THIS FUNCTION 
7c error write -Routine not shown 
find next file ;Check directory 
cmp ax,12H ;Another entry? 
je all done sNo, go home 
jmp write it ;Yes, write record 

all_done: close handle handle ;See Function 3EH 


je error close ;Routine not shown 
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Delete Entry (Function 41h) 


Cail 
AH = 41H 
DS :DX 
Pointer to pathname 


Return 
Carry set: 
AX 
2 = File not found 
5 = Access denied 
Carry not set: 
AX 
No error 





DX must contain the offset (from the segment address in DS) 


of an ASCIZ String that specifies the pathname of the file 
to be deleted. Wild card characters ("*" and "?") cannot be 
used. 


If the file exists and is not read-only, it is deleted. 


If there is an error, the carry flag (CF) is set and the 
error code is returned in AX. 


Code Meaning 
Z Path is invalid or file doesn't exist 
5 Path specifies a directory or read-only file 


To delete a file with the read-only attribute, first change 
its attribute to 0 with Function Request 43H (Change Mode). 


Macro Definition: delete entry macro path 
a MOV dx,offset path 
mov ah,41H 
call loc_50H 
endm 
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Example 


The following program deletes all files on the disk in drive 
B whose date is earlier than December 31, 1981. 


year db 1981 

month db 12 

day db a1 

files db ? 

ten db OAH 

message db "NO FILES DELETED.",0DH,0AH,"$" 

path db "pete", OG 

buffer db 43 dup (?) 

begin: set dta buffer ;See Function lAH 
select disk "B" >See Function OEH 
find first file path,0O ;See Function 4EH 
ic all done ;Go home if empty 

compare: convert date buffer >See end of chapter 
cmp " ©x,year ;After 1981? 
jg next :Yes, don't delete 
cmp d1l,month After December? 
1g next -Yes, don't delete 
cmp dh,day ;3lst or after? 
jge next -Yes, don't delete 
delete entry buffer[1lEH] ;THIS FUNCTION 
jc error delete >Routine not shown 
inc files ;Bump file counter 

next: find next file *Check directory 
jnec compare ;Go home if done 

how_many: cmp files,0 ;Was directory empty? 
je all done ;Yes, go home 
convert files,ten,message ;See end of chapter 

all done: display message ;See Function 09H 


select disk "A" >See Function OEH 


SYSTEM CALLS Function 42H Page 1-132 


Move Pointer (Function 42H) 


1 = Invalid function 
6 = Invalid handle 
Carry not set: 
DX: AX 
New read/write pointer location 


«Capa Call 
x Te Te) AA = 42H 
Cx: | cr fF ce | 
o: | om | o | = Method of moving 
ee ee Handle 
ae ae CX: DX 
ie es Distance in bytes (offset) 
a 
a sneiae 
Carry set: 
| Fuacs» | Faas. | AX 
a ae 
a ae 
| ss 
pee ae 


BX must contain the file handle. CX and DX must contain a 
32-bit offset (CX contains the most significant byte). AL 
must contain a code that specifies how to move the pointer. 


Code Cursor Is Moved To 
OOH Beginning of file plus the offset 
01H Current Pointer location plus the offset 
02H End of file plus the offset 


DX and AX return the new location of the read/write pointer 
(a 32-bit integer; DX contains the most significant byte). 
You can determine the length of a file by setting CX:DX to 0 
and specifying 02H in AL; DX:AX return the offset of the 
byte after the last byte in the file (size of the file in 
bytes). 


If there is an error, the carry flag (CF) is set and the 
error code is returned in AX. 


Code Meaning 


1 AL isn't OOH, O1H, or 02H 
6 Handle isn't open 


SYSTEM CALLS Function 42H Page 1-133 


Macro Definition: move ptr macro handle,high,low,method 


MOV bx,handle 
mov cx,high 
mov dx,low 
mov al,method 
mov ah,42H 
call loc 50H 
endm 7 


Example 


The following program prompts for a letter, converts’ the 
letter to its alphabetic Sequence (A = l, B = 2, etc.), then 
reads and displays the corresponding record from the _ file 
named ALPHABET.DAT in the current directory on the disk in 
drive B. The file contains 26 records; each record is 28 
bytes long. 


file db "b:alphabet.dat",0 

buffer db 26 dup (7),"S” 

prompt db "Enter letter: $" 

CELE db ODH,OAH,"S$" 

handle db 2 

record length dw 28 

begin: open handle file,0 >See Function 3DH 
jc error open ;Routine not shown 
Mov handle,ax ;Save handle 

get char: display prompt ;See Function 09H 
read _kbd_and_ echo ;See Function 01H 
sub al,4lh ;Convert to Sequence 
mul byte ptr record length ;Calculate offset 
move ptr handle,0O,ax,0 ;THIS FUNCTION 
je error move ;ROutine not shown 
read handle handle,buffer,record length 
je error read ;Routine not shown 
cup ax,0 ;End of file? 
je return ;Yes, go home 
display crit ;See Function 09H 
display buffer ;See Function 09H 
display crlf ;See Function 09H 


jmp get char ;Get another character 
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Change Mode (Function 43H) 


Call 
. AH = 43H 
AL = Function 
OOH = Get attributes 
OlH = Set attributes 
CX (if AL = 0O1H) 
Attribute to be set 
DS : DX 
Pointer to pathname 


AX: 
BX: 
Cx: 


OX: 


Return 
Carry set: 
AX 

1 


Invalid function 
3 Path not found 
5 Access denied 
Carry not set: 
CX 
Attributes (if AL = OOH) 


DX muSt contain the offset (from the segment address in DS) 
of an ASCIZ string that specifies the pathname of a file. 
AL must specify whether to get or set the attribute (0 = 
get, = set). If AL = 1, CX must contain an attribute as 
described in Table 1.6. 


rr 


If AL is O, CX returns the current attribute. tt AL 218 1, 
the attribute in CX is set. 


Note that you cannot change the volume-ID bit (08H) or _ the 
directory bit (10H) with this Function Request. 


If there is an error, the carry flag (CF) is set and the 
error code is returned in AX. 


Code Meaning 


I AL isn't OOH or O1H 

3 Path is invalid or file doesn't exist 

5 Attribute in CX cannot be changed (directory or 
volume-id) 


Macro Definition: change mode macro. path,action,attrib 


mov dx,offset path 
Mov al,action 

mov cx,attrib 

mov ah,43H 


call loc_50H 


SYSTEM CALLS 


Example 


The following program displays the 


the file 
disk in drive B. 


Function 43H 


header db 15 dup (20h) ,"Read- 
db "Filename Only 
db "System Volume 
db ODH,0AH,0DH,OAH,"S$" 
path db "b:report.asm",3 dup 
attribute dw 2 
blanks db 9 gup (20h) ,73" 
begin: change mode path,0,0 
4¢ error mode 
mov attribute,cx 
display header 
display path 
mov cx,6 ;Check 
MOv bx,1l ;Start 
chk bit: test attribute,bx 
41z no attr :No 
display char "x" 
jmp short next bit 
no attr: display char 20h 
next bit: display blanks 
shl bx,1 
loop chk_bit ;Check 


attributes 
named REPORT.ASM in the current directory on the 
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asSigned to 


",O0DH,OAH 
Hidden . 
Sub-Dir Archive" 
(0) _ 3" 


sTHIS FUNCTION 
Routine not shown 
;Save attribute byte 
>See Function 09H 
>See Function 09H 


6 bits (0-5) 
with bit 0 


sIs the bit set? 


>See Function 02H 
Done with this bit 
>See Function 02H 
>See Function 09H 
sMove to next bit 


it 
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I/O Control for Devices (Function 44H) 


Call 
AH = 44H 
AL 
Function code 
BG (22 AL. = 4 of AG = 5) 
Drive (0 = default; 1 = Ay, «s<«) 
BX ({(1£ AL=0, 1, 2, 3, G+ OF 7) 
Handle 
c (18 AL & 2, 3, 4, ef 5) 
Bytes to read or write 
DSiDK (1F AGL = 2, 3, 4, Or 5) 
Pointer to data or buffer 
DX (LE AL = 1) 


AX: 
Bx: 
Cx 


DX: 





Data 
Return 
Carry set: 
AX 
1 = Invalid function 
5 = Access denied 
6 = Invalid handle 
13 = Invalid data 
Carry not set: 
If AL -= 0: 
DX 
Data 
If AL = Zy 3, 4, OF 53 
AX 


Bytes transferred 
If AL = 6 or 7 
AL 
00H 
FFH 


Not ready 
Ready 


Either BX must contain the file handle or BL must’ contain 
the drive number. AL must contain a code that specifies the 
function to be performed. 


Code Function 
OOH Get device information 
O1H Set device information 


02H,04H Read from device control channel 
03H,05H Write to device control channel 
06H Get input status 
07H Get output status 


Only codes OOH, O6H, and 07H can be used with disk _ files; 
all codes can be used with devices. 
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Codes OOH and O1H 


Code OOH returns device information; code 01H sets device 
information. If the function code in AL is OOH, DL must 
contain OOH. The device information iS specified Or 
returned in DX; the bits of DX are defined as follows. 


If Bit 7 = 1, the channel is a device; other bits have the 
following meanings: 


Bit Value Meaning 


iS RESERVED. 

14 M4 Device can process control strings if code 
is 02H or 03H. This bit can only be read; 
it cannot be set. 

End of file on input. 

Don't check for control characters. 

Check for control characters. 

RESERVED. 

Clock device. 

Null device. 

Console output device. 

Console input device. 


OrRPNWHL. UO 
PRR rr OrO 


NOTE 


The control characters 
referred to in the description 
of Bit 5 include CONTROL-C, 
CONTROL-P, CONTROL-S, and 
CONTROL-Z. To read these 
characters as data, rather 
than having them interpreted 
as control characters, Bit 5 
must be set and CONTROL-C 
checking must be turned off, 
either with Function Request 
33H or the Break command. 


If Bit 7 = 0, the channel is a disk file; other bits have 
the following meanings: 


Bit Value Meaning 


15-8 RESERVED 
6 0 Channel has been written 
0-5 Block device number of the channel (0 = A, 


l1 = B, etc.). 
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Codes 02H, 03H, 04H, and 05H 


Codes 02H and 03H send or receive control data to or from a 
character device (printer, Serial port, etc.); codes 04H 
and 05H send or receive control data to or from a= block 
device. 


DS must contain the segment address of the area of memory to 
which the data is to be read or from which it is to be 
written; DX must contain the offset. CX must contain the 
number of bytes to be read or written. For codes 02H and 
03H, BX must contain a handle; for codes 04H and 05H, BL 
must contain a drive number (0 = default, 1 = A, etc.). 


AX returns the number of bytes transferred. 


Codes 06H and 07H 


These codes check whether the file or device associated with 
a handle is ready for input (06H) or output (07H). 


BX must contain the handle. 
The status is returned in AL: 


Meaning for Meaning for Meaning for 
Value Device Input File Output File 
OOH Not ready Pointer is at EOF Ready 
OF FH Ready Ready Ready 


An output file always returns ready, even if the disk is 
full. 


If there is an error, the carry flag (CF) is set and the 
error code is returned in AX. 


Code Meaning 


i DH is not O (code 01H) 
AL is not OOH-07H, or the device cannot perform 
the specified function (codes 02H, 03H, 04H, 05H) 


5 Drive in BL is invalid (codes 04H and 05H) 
Access denied (codes 06H and 07H) 

6 Handle is not open (codes 00H-03H, O6H, 07H) 

13 Invalid data (codes 06H and 07H) 
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Macro Definition: io ctrl macro code,handle,buffer,attrib 


mov al,code 
mov bx,handle 
mov cx,attrib 
MOv dx,offset buffer 
mov ah, 44H 
call loc_50H 
endm 
Example 
mov bx,Handle 
(or mov bl,drive for codes 04H and O5H 
0 = default, 1 = A, etc.) 
MOV dx,Data 
(or lds dx, buf and 
Mov cx,count for codes 02H-05H) 
mov ah,44H 
Mov al,code 


call loc_50H 


For codes 02H-05H, AX is the number of bytes transferred 
(same as Read and Write). 

For codes 06H and 07H, AL is status returned, AL=0 if 
status is Not Ready, AL=O0FFH otherwise. 


2e 26 728 OE 
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Duplicate a File Handle (Function 45H) 


«Tepe ] Call 
ex. | eH | ot | AH = 45H 
ox [| a BX 
o [To [a tana 
ne Seas Return 
a ae Carry set: 
a et AX 
as ha 6 = Invalid handle 
4 = Too many open files 
a Carry not set: 
Traces [ naa aX 
. New handle 
| os 
pss 
| 


BX must contain the handle of an open file. 


AX returns a new file handle that refers to the same file at 
the same position. 


After this call, when you move «the read/write pointer of 
either handle, the pointer for the other handle -also moves. 
Usually, this function request is used to redirect standard 
input (handle _ 0) and standard output (handle 1). For a 
description of standard input, Standard output, and the 
advantages and techniques of manipulating them, see Software 
Tools by Brian Ww. Kernighan and Peds Plauger 
(Addison-Wesley Publishing Co., 1976.) 


If there is an error, the carry flag (CF) is set and the 
error code is returned in AX. 


Code Meaning 
4 Too many open files (no handle available) 
6 Handle is not open or is invalid 


Macro Definition: xdup macro. handle 
mov bx,handle 
Mov ah,45H 
call loc_50H 
endm 
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Example 


The following program redefines standard input (handle 1) to 
a file named DIRFILE, invokes a second copy of COMMAND.COM 
to list the directory (which writes the directory to 
DIRFILE), then restores standard input to handle l. 


pgm file db "command.com" ,0 

and line db 9,"/c dir /w",0DH 

parm blk db 14 dup (0) 

path | db "dirfile",0 

new stdout db ? 

begin: set block last inst >See Function 4AH 
je error setblk ;Routine not shown 
create handle path,0 ;See Function 3CH 
jc error create ;ROoutine not shown 
Mov dir file,ax sHandle of new file 
xdup i ;THIS FUNCTION 
je error xdup ;Routine not shown 
mov new _stdout,ax ;Alternate STDOUT 
xdup2 dir file,l >See Function 46H 
jc error xdup2 ;Routine not shown 
exec pgm file,cmd line,parm blk,0 
ic error exec ;Routine not shown 
xdup2 new stdout,1 ;See Function 46H 
je error xdup2 ;Routine not shown 


close handle new_stdout ;See Function 3EH 
j¢ error close ;ROutine not shown 
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Force Duplicate File Handle (Function 46H) 


Call 
AH = 46H 
BX 
Handle 
CX 
Second handle 


Return 
Carry set: 
AX 
6 Invalid handle 
4 Too many open files 
Carry not set: 
AX 
No error 





BX must contain the handle of an open file; CX must contain 
a second file handle. 


If the file referred to by the handle in CX is open, it is 
closed; on return, the handle in CX refers to the same file 
at the same position as the handle in AX. 


After this call, when you move the read/write pointer of 
either handle, the pointer for the other handle also moves. 
Usually, this function request is used to redirect standard 
input (handle 0) and standard output (handle 1). Fora 
Gescription of standard input, standard output, and_ the 
advantages and techniques of manipulating them, see Software 
Tools by Brian W. Kernighan and Pad. Plauger 
(Addison-Wesley Publishing Co., 1976.) 


If there is an error, the carry flag (CF) is set and the 
error code is returned in AX. 


Code Meaning 
4 Too many open file (no handle available) 
6 Handle is not open or is invalid 


Macro Definition: xdup2 macro  handlel,handle2 


mov bx,handlel 
mov cx,handle2 
mov ah,46H 


call loc_50H 
endm 
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Example 


The following program redefines standard input (handle 1) to 
a file named DIRFILE, invokes a second copy of COMMAND.COM 
to list the directory (which writes the directory to 
DIRFILE), then restores standard input to handle l. 


pgm file db "command.com",0 

cmd line db 9,"/c dir /w",O0DH 

parm blk db 14 dup (0) 

path — db *"Girtiie* .o 

new stdout db ? 

begin: set block last_inst ;See Function 4AH 
je error setblk ;Routine not shown 
create handle path,0 ;See Function 3CH 
1c error create >Routine not shown 
Mov dir file,ax sHandle of new file 
xdup : ae ;See Function 45H 
je error xdup ;Routine not shown 
MOV new stdout,ax ;Alternate STDOUT 
xdup2 dir file,l ;THIS FUNCTION 
jc error xdup2 >Routine not shown 
exec pgm file,cmd_line,parm_blk,0 
jc error exec s;Routine not shown 
xdup2 new stdout,1 :THIS FUNCTION 
jc error xdup2 ;Routine not shown 


close handle new_stdout ;See Function 3E 
je error close ;Routine not shown 
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Get Current Directory (Function 47H) 


Call 
AH = 47H 
S251 
Pointer to 64-byte memory area 
DL 
Drive number 


AX 

BX: 
Cx: 
Dx: 


Return 
Carry set: 
AX 
15 = Invalid drive 
Carry not set: 
AX 
No error 





DL must contain a drive number (0 = default, 1= A, etc.). 


SI must contain the offset (from the segment address in DS) 
of a 64-byte memory area. 


The call places an ASCIZ string that specifies the full 
pathname of the current directory for the specified drive, 
Starting from the root directory, in the memory area. The 
String does not begin with a backslash and does not include 
the drive letter. 


If there is an error, the carry flag (CF) is set and the 
error code is returned in AX. 


Code Meaning 
15 Drive in DL is invalid 


Macro Definition: get dir macro  drive,buffer 


mov dl,drive 
Mov si,offset buffer 
mov ah,47H 


call loc_50H 
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Example 


The following program displays the current directory on 
disk in drive B. 


disk db ‘bie 

buffer db 64 dup (?) 

begin: get dir 2,buffer ;THIS FUNCTION 
je error dic ;ROutine not shown 
display disk ;See Function 09H 


display asciz buffer *See end of chapter 


the 
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Allocate Memory (Function 48H) 


« Cw Ta] Call 

oe AH = 48H 

cx BX 

= Ton | oo Paragraphs of memory 


Return 
Carry set: 
AX 
: 
8 
BX 
Paragraphs of memory available 
Carry not set: 
AX 
Segment address of allocated memory 


Memory control blocks damaged 
Insufficient memory 


mn 
i 


BX must contain the amount of memory requested, in 
paragraphs (1 paragraph = 16 bytes). 


AX returns the segment address (with an implied offset of 0) 
of the allocated memory. If the allocation fails, BX 
returns the maximum number of paragraphs of contiguous 
memory that could be allocated. 


If there is an error, the carry flag (CF) is set andthe 
error code is returned in AX. 


Code Meaning 
7 Memory control blocks damaged (a user program 
changed memory that doesn't belong to it) 
8 Not enough free memory available 


Macro Definition: allocate memory macro bytes 


mov bx, bytes 
Mov c1,4 

shr pet ,cl1 
inc bx 

mov ah,48H 
call loc 50H 


endm 


SYSTEM CALLS 


Example 


The following program opens 
calculates its size with 
block of memory the size of 
the allocated memory block, 


Function 48H 
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the file named TEXTFILE.ASC, 
Move Pointer (42H), allocates a 
the file, reads tthe file into 
then frees the allocated memory. 


path db "textfile.asc",0 
handle dw ? 

mem seg dw 2 

file len dw ? 

begin: open handle path,0 


jc 


mov handle,ax 


move ptr handle,0,0,2 


jc error move 
Mov file len,ax 
set block last inst 
je error setblk 
allocate memory 

je érror alloc 
mov mem seg,ax 
mov ptr handle,O,0,0 
qc error move 
push ds 

mov ax,mem seg 
mov ds,ax | 


read handle 


=e 


pop ds 


jc 


=e 


free memory 
je 


error open 


error read 
<CODE TO PROCESS FILE GOES HERE> 
mem seg 
error freemem ;Routine not shown 


;Routine not shown 
*Save handle 

>See Function 42H 
;Routine not shown 
;Save file length 
>See Function 4AH 
>Routine not shown 


file len ;THIS FUNCTION 


s>Routine not shown 

;Save address of new memory 
>See Function 42H 

Routine not shown 

;Save DS 

;Get segment of new memory 
;Point DS at new memory 


handle,code,file len ;Read file into 


new memory 
;Restore DS 
Routine not shown 


*See Function 49H 
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Free Allocated Memory (Function 498) 


« [ow Ta Call 

= [ow [om] = AH = 49H 

Segment address of memory to be 
freed 


Return 

Carry set: 

AX 
7 = Memory control blocks damaged 
9 = Incorrect segment 

Carry not set: 
No error 


ES must contain the segment address of the memory area being 
returned. 


The specified area of memory is returned to the system pool. 
The memory must have been allocated with Function Request 
48H (Allocate Memory). 


If there is an error, the carry flag (CF) is set and the 
error code is returned in AX. 


Code Meaning 
7 Memory control blocks damaged (a user program 
changed memory that doesn't belong to it) 
9 The memory pointed to by ES was not allocated 
with Function Request 48H 
Macro Definition: free memory macro seg addr 
Mov ax,seg addr 
mov es,ax 
Mov ah,49H 
call loc _ 50H 


SYSTEM CALLS 


Example 


The following program opens 
calculates its size with 
block of memory the size of 
the allocated memory block, 


path db "textfile. 
handle dw 2 
mem seg dw a 
file len dw ¢ 
begin: open handle _ path, 


7c 
MOV 


jc error move 
MOV file len,ax 
set block last inst 
jc error setblk 
allocate memory 

je error alloc 
Mov mem seg,ax 
mov_ ptr handle,0O,0,0 
ye error move 
push ds 

Mov ax,mem seg 
mov ds,ax 


read handle 


pop ds 


je 


Function 49H 


error open 
handle,ax 
move ptr handle,O, 


file len 


error read 
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the file named TEXTFILE.ASC, 
Move Pointer (42H), allocates a 
the file, reads the file into 


then frees the allocated memory. 


asc",0 


0 

;ROutine not shown 

;Save handle 

>See Function 42H 

;ROutine not shown 

Save file length 

>See Function 4AH 

Routine not shown 

>See Function 48H 
-Routine not shown 

Save address of new memory 
>See Function 42H 

;ROoutine not shown 

;Save DS 

;Get segment of new memory 
;Point DS at new memory 


OyZ 


handle,code,file len ;Read file into 


new memory 
;Restore DS 
;Routine not shown 


<CODE TO PROCESS FILE GOES HERE> 


free memory 
je 


mem seg 
error freemem ;Routine not shown 


;THIS FUNCTION 
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Set Block (Function 4AH) 


Paragraphs of memory available 
Carry not set: 
No error 


a Call 
x [| a AH = 4AH 
a [o | a_| BX 
ox [ om | om | Paragraphs of memory 
ES 
SP Segment address of memory area 
BP 
Foe Return 
a Carry set: 
ae > 
7 = Memory control blocks damaged 
[ Fuacs. | macs | 8 = Insufficient memory 
cs 9 = Incorrect Segment 
edt Seay By 
De Me 
a a 


ES must contain the segment address of the area of memory to 
be modified (for a program, this is the start of the Program 
Segment Prefix). BX must contain the new amount of memory 
requested, in paragraphs (1 paragraph = 16 bytes). 


MS-DOS attempts to change the size of the area of memory. 
If the call fails on a request to increase memory, BX 
returns the maximum number of paragraphs of memory to which 


the program can be increased. 


If there is an error, the carry flag (CF) is set and the 
error code is returned in AX. 


Code Meaning 
2 Memory control blocks destroyed (a user program 
changed memory that doesn't belong to it) 
8 Not enough free memory 
9 The memory pointed to by ES cannot be allocated 


with Set Block 


Macro Definition: set block macro last byte 


mov bx,offset last byte 
mov ei ,4 

shr bx, cl 

inc bx 

mov ah, 4AH 

call loc_50H 


endm 
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Example 


The following program invokes a Second copy of COMMAND.COM 
and executes a DIR (directory) command. 


pgm file db "command.com",0 

cmd line db 9,"/c dir /w",0DH 

parm blk db 14 dup (?) 

reg save db 10 dup (?) 

begin: set block last inst ;THIS FUNCTION 
exec pgm file,cmd line,parm_blk,0 ;See Function 


:4BH 
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Execute Program (Function 4BH) 


Call 
« Cw [ « AH = 4BH 
ox [om | a AL 
cx: OOH = Load and execute program 
ox | of | om | 03H = Load overlay 
DS :DX 
mz ae Pointer to pathname 
aa ES : BX 
el Pointer to parameter block 
aes 
Pe) 
[rues [race aa 
a ae 1 = Invalid function 
ee ae 2 = File not found 
8 = Insufficient memory 
A. 10 = Bad environment 
1l = Bad format 


Carry not set: 
No error 


DX must contain the offset (from the segment address in DS) 
of an ASCIZ string that specifies the drive and pathname of 
an executable program file. BX must contain the offset 
(from the segment address in ES) of a parameter block. AL 
must contain a code that specifies whether to execute the 
program. 


Code Meaning 
00H Load and execute the program. 
03H Load an overlay (or program). 


Code 00H -- Load and Execute Program 


There must be enough free memory for MS-DOS to load _ the 
program file. Usually, all available memory is allocated to 
the invoking program when it is loaded, so you must free 
some memory with Set Block (Function Request 4AH) before 
loading another program with this function request. Unless 
memory is needed for some other purpose, shrink to the 
minimum amount of memory the invoking program needs. 
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A Program Segment Prefix is created for the program being 
loaded; the terminate and CONTROL-C addresses are set to 
the instruction that immediately follows the Execute Program 
Function Request in the invoking program. 


The following is the format of the parameter block if the 
program is to be executed. 


Offset Length 
(Hex) (Bytes) Description 


00 2 (word) Segment address of environment to be 
passed; OOH means copy the parent's 
environment. 


02 4 (dword) Segment:Offset of command line to be 
Dlaced at offset 80H of the new 
Program Segment Prefix. This must 
be a correctly formed command line 
no longer than 128 bytes. 


06 4 (dword) Segment:Offset of FCB to be placed 
at offset 5CH of the new Program 
Segment Prefix. (See the 


description of the Program Segment 
Prefix in Chapter 4.) 


OA 4 (dword) Segment:Offset of FCB to be placed 
at offset 6CH of the new Program 
Segment Prefix. (See the 
description of the Program Segment 
Prefix in Chapter 4.) 


All open files of a program are available to the newly 
loaded program, giving the parent program control over the 
definition of standard input, output, auxiliary, and printer 
devices. For example, a program could write a series of 
records to a file, open the file as standard input, open a 
second file as standard output, then use Execute Program to 
load and execute a program that takes itS input’ from 
standard input, sorts records, and writes to standard 
output. 
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The loaded program also receives an environment, a series of 
ASCIZ strings of the form parameter=value (for example, 
VERIFY=ON). The environment must begin on a= paragraph 
boundary, be less than 32K bytes long, and end with a byte 
of OOH (that is, the final entry consists of an ASCII string 
followed by two bytes of OOH). The loaded program either 
inherits a copy of the parent's environment or receives a 
new environment built for it by the parent. 


Place the segment address of the environment at offset 2CH 
of the new Program Segment Prefix. To build an environment 
for the loaded program, put it on a paragraph boundary = and 
place the segment address of the environment in the first 
word of the parameter block. To pass a copy of the parent's 
environment to the loaded program, put OOH in the first word 
of the parameter block. 


Code 03H -- Load But Don't Execute 

MS-DOS assumes that the invoking program is loading into its 
own address space, so no free memory is required. A Program 
Segment Prefix is not created. This code is used to load a 
program overlay. 


The format of the parameter block: 


Offset Length 


(Hex) (Bytes) Description 

00 2 (word) Segment address where program is to 
be loaded. 

02 2 (word) Relocation factor (typically, this 


is the same as the word at OOH; see 
the description of the .EXE file 
format in Chapter 5). 


If there is an error, the carry flag (CF) is set and the 
error code is returned in AX. 


Code Meaning 
1 AL is not OOH or 03H 
Program file not found or path is invalid 
8 Not enough memory to load the program 

Li Program file is an .EXE file that contains 


internally inconsistent information 


SYSTEM CALLS 


Function 4BH 


Macro Definition: 


exec 


Example 


macro path,command,parms,function 
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parms[02H] ,offset command 


Mov dx,offset path 

mov bx,offset parms 

mov word ptr 

mov word ptr parms[04H],cs 
mov word ptr parms[06H] ,5CH 
Mov word ptr parms[08H],es 
MOV word ptr parms[OAH] ,6CH 
Mov word ptr parms[0OCH],es 
mov al,function 

mov ah,4BH 


call loc 50H 


The following program invokes a second copy 


and executes a DIR 


pgm file db 
cmd line db 
parm blk db 
reg save db 
begin: 
set block 
exec 


(directory) command: 


"command.com",0 
9,"7e dir /w",0DH 


14 dup 
10 dup 


last inst 


(?) 
(?) 


or 


COMMAND .COM 


>See Function 4BH 


pgm file,cmd line,parm blk,0 ;THIS FUNCTION 
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End Process (Function 4CH) 


o Tm Ta Call 

ox [on [a AH = 4CH 

co es ah 

o: [ of | o | Return code 
Return 
None 


AL contains a return code, 


All open handles are closed, the current process is’ ended, 
and control returns to the invoking process. The return 
code can be retrieved with Wait (Function Request 4DH) = and 
the batch subcommands IF and ERRORLEVEL. 


This function request doesn't require that CS contain’ the 
segment address of the Program Segment Prefix. You should 
use it to end a program (rather than Interrupt 20H or a jump 
to location 0) unless your program must be compatible with 
earlier versions of MS-DOS. 


Macro Definition: end process macro’. return code 
om Mov al,return code 
MOV ah,4CH  —— 
Gall loc 50H 
endm 7 
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Example 


The following program displayS a message and returns to 
MS-DOS with a return code of 8. It uses only the opening 
portion of the sample program skeleton shown in Figure 1.2. 


message db "Displayed by FUNC 4CH example",0DH,0AH,"$" 
begin: display message ;See Function 09H 

end process 8 ;THIS FUNCTION 
code ends 


end code 


SYSTEM CALLS Function 4DH 
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Wait (Function 4DH) 





Call 
AH = 4DH 


Return 
AX 
Return code 


AL returns the return code specified by a child program 
(with Function Request 31H or 4CH). AH returns a code that 
specifies the reason the program ended. 


Code 


OOH 
01H 
02H 
03H 


Meaning 


Normal ending 

CONTROL-C 

Critical device error 

Function 31H (Terminate and Stay Resident) 


The exit code is returned only once. 


No macro definition or example is included for Function 40H. 
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Find First File (Function 4ER) 


AX: 
BX: 
Cx: 
Ox: 


poe fo 
ae 
pom | a 
| om | om | 
ae ae 
ae ee 
eS 
a ae Carry set: 
a eel 
LFiscs» | Faas 
ne ee 
ae 
tg | 
DO 


Call 
AH = 4EH 
DS :DX 
Pointer to pathname 
CX 
Attributes to match 


Return 


AX 
2 = File not found 
18 = No more files 
Carry not set: 
No error 


DX must contain the offset (from the segment address in 

of an ASCIZ String that specifies a path and filename; 

filename can contain global characters ("*" and "?"), 

must contain the attribute to be used in searching for 
file, as described in Table 1.6. 


If a directory entry is found that matches the name 


attribute, 
Offset 


OOH 


the current DTA is filled as follows: 
Length Description 


21 Reserved for subsequent Find Next 
File (Function Request 4FH). 


l Attribute found. 

2 Time file was last written. 

2 Date file was last written. 

2 Low word of file size, 

2 High word of file size. 

Le Name and extension of the file, 


followed by OOH. All blanks are 
removed; if there is an extension, 


LS? 


DS) 
the 

CX 
the 


and 


nT 


is preceded by a period (it appears 


just as you would enter it ina 
command) . 
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NOTE 


If the attribute field is’ set 
for hidden or system files, or 


directory entries, Lt is 
considered to be an inclusive 
search. All normal file 
entries plus all entries 
matching the specified 


attributes are returned. To 
look at all directory entries 
except the volume label, the 
attribute byte may be set to 
hidden + system + directory 
(all 3 bits on). 


If there is an error, the carry flag (CF) lis set andthe 
error code is returned in AX. 


Code Meaning 
2 Path is invalid 
18 No matching directory entry 


Macro Definition: find first file macro path,attrib 


mov dx,offset path 
mov ox ,attrib 
MOV ah,4EH 


call loc_50H 
endm 
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Example 
The following program displays a message that specifies 
whether a file named REPORT.ASM exists in the current 
directory on the disk in drive B. 
yes db “FILE EXISTS." ,0DH,OAH,"3” 
no db "FILE DOES NOT EXIST.” ,0ODH,OAH,"$" 
path db “bz: report.asm",0 
buffer db 43 dup (?) 
begin: set dta buffer >See Function 1AH 
find first file path,0 ;THIS FUNCTION 
IC error findfirst ;Routine not shown 
cmp al,1l2H File found? 
je not there >No 
display yes >See Function 09H 
jmp return ;All done 


not there: display no 


>See Function 09H 


SYSTEM CALLS Function 4FH Page 1-162 


Find Next File (Function 4FH) 


Call 
AH = 4FH 


poe | | 
Lt 
po | a | 
[om [| Return 
Carry set: 
i aa AX 
ee | 18 = No more files 
a ee Carry not set: 
a 
a ee 
[Lriacsn | Faas. | 
a lay 
a 
i ae 
a ae 


No error 


The current DTA must contain the information filled in by a 
previous Find First File (Function Request 4EH). 


MS-DOS searches for the next directory entry that matches 
the name and attributes specified in the previous Find First 
File (Function Request 4EH). 


If a matching entry is found, the current DTA is filled just 
as it was for Find First File. 


Offset Length Description 


00H 21 Reserved for subsequent Find Next 
File (Function Request 4FH). 


15H I Attribute found. 

16H 2 Time file was last written. 

18H 2 Date file was last written. 

1AH 2 Low word of file size. 

1CH 2 High word of file size. 

1EH 13 Name and extension of the file, 


followed by OOH. All blanks are 
removed; if there iS an extension, it 
is preceded by a period (it appears 
just as you would enter it ina 
command). 
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If there is an error, the carry flag (CF) is set and _ the 
error code is returned in AX. 


Code Meaning 
2 Path is invalid 
18 No matching directory entry 
Macro Definition: find next file macro 
oe oe mov ah,4FH 
call loc_50H 
endm 


Example 


The following program displays the number of files in the 
current directory on the disk in drive B. 


message db "No files",0ODH,OAH,"S$" 
files db ? 
ten db OAH 
path db “hae, "50 
buffer db 43 dup (?) 
begin: set dta buffer >See Function lAH 
find first file path,0 ;See Function 4EH 
1c error findfirst ;Routine not shown 
cmp al,12H ;Directory empty? 
je all done ;Yes, go home 
inc files >No, bump file counter 
Search dir: find next file ;THIS FUNCTION 
j¢ error findnext ;Routine not shown 
cmp al, 12H ;Any more entries? 
je done ;No, go home 
inc files ;Yes, bump file counter 
jmp search dir >And check again 
done: convert files,ten,message ;See end of chapter 


all done: display message ;See Function 09H 
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Get/Verify State (Function 54H) 


Call 


RF & 


Return 
AL 


01H 


AH = 54H 


Current verify status 
OOH = No verify after write 


Verify after write 


AL returns OOH if verify is off, O1H if verify is on. 


The verify status can be set 
Function Request 2EH. 


Macro Definition: get verify 


Example 


with Set/Reset Verify 


macro 
Mov ah,54H 
call loc_50H 
endm 


The following program displays the verify status: 


message db "Verify “,"3"* 

on db “On. * ,0DH,0AH, "S* 

off db "OLE." ,ODH,0AH, "3" 

begin: display message ;See Function 09H 
get verify ;THIS FUNCTION 
cmp al,0 sis flag offi? 
1g ver on ‘No, it’s on 
display off ;See Function 09H 
jmp return ;Go home 


ver on: display on 


>See Function 09H 
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Flag, 
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Rename a File (Function 56H) 


. Ce et Call 

AX 

ay Se ee 

o [om fa | —-PS:DX. 

ox [ om | ao | Br tis to pathname 
PSR Pointer to second pathname 
a eee Return 
[w=] Carry set: 

AX 

Pe | = File not found 
| FuaGs. | Fisas | 5 = Access denied 
— ae 17 = Not same device 
| 


DX must contain the offset (from the Segment address in DS) 
of an ASCIZ string that contains an optional drive and 
path, and a filename. DI must contain the offset (from the 
segment address in ES) of an ASCIZ string that contains a 
second optional drive and path, and a filename. 


If the first file exists, it is renamed to the second name. 


If the second path specifies a drive, the first path must 
specify or imply the same drive. The directory paths do not 
need to be the same, allowing you to move a file to another 
directory at the same time you rename it. 


If there is an error, the carry flag (CF) is set and the 
error code is returned in AX. 


Code Meaning 
2 File not found or path is invalid 
5 First pathname specifies a directory; second 


path specifies an existing file; or the second 
directory entry could not be opened 
17 Files not on the same drive 
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Macro Definition: rename file macro 


Example 


MOV 
push 
pop 
mov 
mov 
call 
endm 
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old path,new path 
dx,offset old pat 
ds _ 

es 

di,offset new path 
ah,56H 7 
loc_50H 


The following program prompts for the name of a file and a 


new name, 


promptl 
prompt2 
old path 
new path 
crlf 


begin: 


then renames the file. 


db "Filename: $" 
db "New name: $" 
db 15,?,15 dup (?) 
db 15,727,135 dap {7} 
db ODH,OAH,"S$" 


display promptl 
get _ string 15,old path 


XxOr Ox, Ox 
mov b1l,old path[1] 
mov Old path[bx+2],0 


display crlf 
display prompt2 
get string 15,new path 


XxOr 0x, Dx 
MOV bl,new path[1] 
Mov new path[bx+2] ,0 


display crlf 


>See Function 09H 
>See Function OAH 

;To use BL as index 
;Get String length 
;Make an ASCIZ string 
>See Function 09H 
:;See Function 09H 
>See Function OAH 

;ToO use BL as index 
;Get string length 
sMake an ASCIZ string 
See Function 09H 


rename file old path[2],new_path[2];THIS FUNCTION 


je error rename 


*>Routine not shown 
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Get/Set Date or Time (Function 57H) 


1 = Invalid function 

6 = Invalid handle 
Carry not set: 
CX (if AL = OOH) 

Time file last written 
DX (1f AL = OOH) 

Date file last written 


Call 
“FR, 
™ ow | a AL = Function code . 
. a OOH = Get date and time 
Ol1H = Set date and time 
a BX 
ina eae Handle 
ae ae CX (1£ AL = O01} 
ae Time to be set 
DX (if AL = O1H) 
aa ae Date to be set 
| FLNGS» | LAGS. 
[sd een 
ec ay Carry set: 
Le i 
a Tee 


AL must contain either 0 to get the date and time or 1 to 
set the date and time. BX must contain the file handle. If 
AL=l1, CX must contain the time and DX must contain the date, 
in the form described in Table 1.2. 


If AL=0, CX returns the time and DX returns the date, in the 
same form. 


If there is an error, the carry flag (CF) is set and the 
error code is returned in AX. 


Code Meaning 
Mov bl,new path[1] ;Get string length 
1 AL is not OOH or O1H 


6 Handle is not open 
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Macro Definition: 


Page 1-168 


get_set date time macro handle,action,time,date 


Mov bx,handle 

mov al,action 

mov cx,word ptr time 
mov dx,word ptr date 
Mov ah,57H 

call loc 50H 

endm . 


Example 


The following program gets the date 
REPORT.ASM in the current directory on 


of the file named 
the disk in drive B, 


increments the day, increments the month or year Lt 

necessary, and sets the new date of the file. 

month db Slip 2B pode S07 oy 304351517305 31h¢ 3023 

path db “b:report.asm",0 

handle dw ? 

time db 2 dup (?) 

date db 2 dup (?) 

begin: open handle _ path,0 ;See Function 3DH 
mov handle,ax ;Save handle 
get set date time handle,0,time,date; THISFUNCTION 
jc error time >-Routine not shown 
mov word ptr time,cx >Save time 
mov word ptr date,dx Save date 
convert date date[-24] >See end of chapter 
inc dh ;Increment day 
XOL bx, bx 7To use BL as index 
mov bl,dl :;Get month 
cmp dh,month [bx-1] ;Past last day? 
jle month ok ;No, go home 
Mov dh,l ;Yes, set day to l 
inc dl ;Increment month 
cmp al,i2 7;Is it past December? 
jle month ok ;No, go home 
MOV dil -Yes, set month to 1 
inc cx ;Increment year 

month ok: pack date date ;See end of chapter 

. get set date time handle,1l,time,date; THISFUNCTION 

jc error time ;Routine not shown 
close handle handle ;See Function 3EH 


4¢ error close >Routine not shown 
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1.9 MACRO DEFINITIONS FOR MS-DOS SYSTEM CALL EXAMPLES 
REEREDEAEEERAKRERED 


‘ 
; Interrupts 
eR RKKKKEKKKKKEKKKKKKKK 


1 INTERRUPT 25H 
ABS DISK READ macro disk,buffer,num sectors,first sector 
FOV” al,disk ~ ~ 
mov bx,offset buffer 
Mv cx,num sectors 
mv dx,first sector 
int 25H 
pop. 
endm 
4 INTERRUPT 26H 
ABS DISK WRITE macro disk,buffer,num_sectors,first sector 
MOV al,disk 
mov bx,offset buffer 
mv cx,num_ sectors 
MOV ax,first sector 
int 26H 
popf 
endm 
‘ INTERRUPT 27H 
STAY RESIDENT macro last instruc 
~ Mov dx,offset last instruc 
inc dx 
int 27H 
endm 


kRaekKkKkKkKeKRKKKKKKKkKKEKK 


Function Requests 
wKaekkkkkek kkk KRKRKKR KR KKK 


=e =e te «TS SO NO 


FUNCTION REQUEST 00H 
TERMINATE PROGRAM macro 


xOr ah,ah 

call loc _50H 

endm 
: FUNCTION REQUEST 01H 
READ KBD AND ECHO macro 

~ Mov ah,01H 
call loc_50H 
endm 


: FUNCTION REQUEST 02H 
DISPLAY CHAR macro character 


MOV dl,character 
mov ah,02H 
call loc _ 50H 
endm 
: FUNCTION REQUEST 03H 
AUX INPUT macro 
~ mov ah,03H 


call loc _50H 


MACRO DEFINITIONS 


endm 


AUX OUTPUT 
~ mov 
call 

endm 


PRINT CHAR 
Mov 
MOV 
call 
endm 


macro 
ah,04H 
loc 50H 


macro character 
dl,character 
ah,0O5H 

loc_50H 


DIR_CONSOLE IO macro switch 


mov 
mov 

call 
endm 


dl,switch 
ah,06H 
loc_50H 


DIR_CONSOLE INPUT macro 


mov 
call 
endm 


ah,07H 
loc_50H 


READ_KBD macro 


mov 
call 
endm 


ah,08H 
loc_50H 


DISPLAY macro- string 


mov 
mov 
call 
endm 
GET STRING 
~ mov 
mov 
mov 
call 
endm 


dx,offset string 
ah,0O9H 
loc_50H 


Macro limit,string 
dx,offset string 
String,limit 

ah, OAH 

loc _50H 


CHECK KBD STATUS macro 


mov 
call 
endm 


FLUSH AND READ KBD macro 


mov 
mov 
call 
endm 


RESET DISK 
mov 


ah, OBH 
loc_50H 


al,switch 
ah,0OCH 
loc 50H 


macro 
ah, ODH 


Switch 


FUNCTION 


FUNCTION 


FUNCTION 


FUNCTION 


FUNCTION 


FUNCTION 


FUNCTION 


FUNCTION 


FUNCTION 


FUNCTION 


REQUEST 


REQUEST 


REQUEST 


REQUEST 


REQUEST 


REQUEST 


REQUEST 


REQUEST 


REQUEST 


REQUEST 
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04H 


05H 


06H 


07H 


08H 


09H 


OAH 


OBH 


OCH 


ODH 


MACRO DEFINITIONS 
call loc 50H 
endm 


SELECT DISK macro disk 
mov d1l,disk[-65] 


mov ah,0OEH 
call loc 50H 
endm 


OPEN macro fcb 


MOV dx,offset fcb 
mov ah,0OFH 

call loc 50H 

endm 7 


CLOSE macro. fcb 


mov dx,offset fcb 
MOV ah, 10H 

call loc_50H 

endm 


SEARCH FIRST macro fcb 


mov dx,offset fcb 
mov ah,11H 

call loc_50H 

endm 


SEARCH NEXT macro- fcb 


mov dx,offset fcb 
mov ah,12H 

call loc_50H 

endm 


DELETE macro- fcb 


mov dx,offset fcb 
mov ah,13H 

call loc_50H 

endm 


READ SEQ macro fcb 


Mov dx,offset fcb 
mMOv ah,14H 

call loc 50H 

endm 7 


WRITE SEQ macro fcb 


mov dx,offset fcb 
mov ah,15H 

call loc 50H 

endm ~ 


CREATE macro- fcb 
mov dx,offset fcb 
mov ah,16H 
call loc_50H 


FUNCTION 


FUNCTION 


FUNCTION 


FUNCTION 


FUNCTION 


FUNCTION 


FUNCTION 


FUNCTION 


FUNCTION 


REQUEST 


REQUEST 


REQUEST 


REQUEST 


REQUEST 


REQUEST 


REQUEST 


REQUEST 


REQUEST 
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OEH 


OFH 


10H 


11H 


12H 


13H 


15H 


16H 


MACRO DEFINITIONS 


endm 


RENAME macro’ fcb,newname 


mov dx,offset fcb 
mov ah,17H 

call loc 50H 

endm 7 


CURRENT DISK macro 


mov ah, 19H 
call loc_50H 
endm 


SET DTA macro buffer 


Mov dx,offset buffer 
mov ah, 1AH 
call loc SO0H 
endm - 
READ RAN macro- fcb 
~ MOV dx,offset fcb 
mov ah,21H 
call loc 50H 
endm - 
WRITE RAN macro fcb 
Mov dx,offset fcb 
mov ah,22H 
call loc_50H 
endm 
FILE SIZE macro fcb 
~ mov dx,offset fcb 
mov ah,23H 
call loc_50H 
endm 


SET RELATIVE RECORD macro fcb 
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FUNCTION REQUEST 17H 


FUNCTION REQUEST 19H 


FUNCTION REQUEST 1AH 


FUNCTION REQUEST 21H 


FUNCTION REQUEST 22H 


FUNCTION REQUEST 23H 


FUNCTION REQUEST 24H 


FUNCTION REQUEST 25H 


Mov dx,offset fcb 
mov ah,24H 
call loc_50H 
endm 
SET VECTOR macro. interrupt,handler start 
~ Mov al,interrupt 
mov dx,offset handler start 
Mov ah, 25H 
call loc_50H 
endm 


RAN BLOCK READ macro 


FUNCTION REQUEST 27H 


feb,count,rec_ size 


Mov dx,offset fcb 

mov cx,count 

mov word ptr fcb[14],rec_size 
Mov ah,27H 
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call loc_50H 

endm 
; FUNCTION REQUEST 28H 
RAN BLOCK WRITE macro’ fcb,count,rec size 


mov dx,offset fcb 

mov cx,count 

mov word ptr fcb[14],rec size 
MOV ah, 28H = 
call loc_50H 

endm 


: FUNCTION REQUEST 29H 
PARSE macro’ string,fcb 


Mov si,offset string 
mov di,offset fcb 
push es 

push ds 

Pop es 

mov al,OFH 

mov ah,29H 

call loc 50H 

pop es 

endm 


; FUNCTION REQUEST 2AH 
GET DATE macro 


mov ah, 2AH 
call loc_50H 
endm 


: FUNCTION REQUEST 2BH 
SET DATE macro year,month,day 


mov cx,year 
Mov dh,month 
mov dl1l,day 
Mov ah, 2BH 
call loc_50H 
endm 


; FUNCTION REQUEST 2CH 
GET TIME macro 


MOV ah, 2CH 
call loc_50H 
endm 


; FUNCTION REQUEST 2DH 
SET TIME macro hour,minutes,seconds,hundredths 


mov ch,hour 

mov cl,minutes 
mov dh,seconds 
Mov d1,hundredths 
mov ah, 2DH 

call loc_50H 

endm 


: FUNCTION REQUEST 2EH 
VERIFY macro switch 

mov al,switch 

mov ah, 2EH 

call loc_50H 

endm 


MACRO DEFINITIONS 


GET DTA macro 
GET VERSION macro 


CTRL € CK Macro action,state 


GET VECTOR macro interrupt 


GET DISK SPACE macro drive 


a 


FUNCTION REQUEST 2FH 


MOV ah,2FH 
call loc_50H 
endm 


FUNCTION REQUEST 30H 


mov ah, 30H 
call loc 50H 
endm 


FUNCTION REQUEST 33H 


mov al,action 
mov d1l,state 
mov ah,33H 
call loc 508 
endm a 


FUNCTION REQUEST 35H 


MOV al,interrupt 
mov an, 35H 

call loc_50H 

endm 


FUNCTION REQUEST 36H 


mov dl,drive 
mov ah, 36H 
call loc 50H 
endm _ 


; FUNCTION REQUEST 38H 


GET COUNTRY macro mem_area,action 


MAKE DIR macro path 


REM DIR macro path 


CHANGE DIR macro path 


=e 


Mov dx,offset mem area 
mov al,action - 

mov ah, 38H 

call loc 50H 

endm 7 


FUNCTION REQUEST 39H 


mov dx,offset path 
mov ah,39H 

call loc_50H 

endm 


FUNCTION REQUEST 3AH 


MOV dx,offset path 
Mov ah, 3AH 

call loc_ 50H 

endm 


FUNCTION REQUEST 3BH 


MOV dx,offset path 
mov ah, 3BH 

call loc 50H 

endm - 


FUNCTION REQUEST 3CH 
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CREATE HANDLE macro. path,attrib 


MOV dx,offset path 
mov cx,attrib 

MOV ah, 3CH 

call 106 SUG 

endm i 


; FUNCTION REQUEST 3DH 
OPEN HANDLE macro path,access 


mov dx,offset path 
mov al,access 

MOV ah,3DH 

call loc_50H 

endm 


; FUNCTION REQUEST 3EH 
CLOSE HANDLE macro _ handle 


MOv bx,handle 
mov ah, 3EH 
call loc 50H 
endm - 


; FUNCTION REQUEST 3FH 
READ HANDLE macro handle,buffer,bytes 


Mov bx,cs:handle 

mov dx,offset buffer 
mov cx,cs:bytes 

MOV ah, 3FH 

call cs:loc_ 50H 

endm 


; FUNCTION REQUEST 41H 
DELETE ENTRY macro path 


mov dx,offset path 
mov ah,41H 

call loc_50H 

endm 


: FUNCTION REQUEST 42H 
MOVE PTR macro  handle,high,low,method 


mov bx,handle 
MOV cx,high 
mov dx, low 
MOV al,method 
mov ah,42H 
call loc_50H 
endm 


; FUNCTION REQUEST 43H 
CHANGE MODE macro path,action,attrib 


MOv dx,offset path 
MOV al,action 

mov cx,attrib 

MOv ah,43H 

call loc_50H 

endm 


: FUNCTION REQUEST 44H 
IO CONTROL macro’ code,handle,buffer,attrib 

mov al,code 

mov bx,handle 

mov dx,offset buffer 
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mov cx,attrib 
Mov ah,44H 
call loc 50H 
endm 


: FUNCTION REQUEST 45H 
XDUP macro handle 


mov bx,handle 
mov ah,45H 
call loc_50H 
endm 


: FUNCTION REQUEST 46H 
XDUP2 macro handlel,handle2 


Mov bx, handlel 
mov cx,handle2 
mov ah,46H 
call loc 50H 
endm ne 


; FUNCTION REQUEST 47H 
GET DIR macro drive,buffer 


mov dl,drive 

mov si,offset buffer 
MOV ah,47H 

call loc 50H 

endm 


; FUNCTION REQUEST 48H 
ALLOCATE MEMORY macro paragraphs 


mov bx,paragraphs 
mov cl1,4 

shr Dx ;Cl 
inc bx 

mov ah,48H 

call loc_50H 

endm 


; FUNCTION REQUEST 49H 
FREE MEMORY macro seg_ addr 


mov ax,seg addr 
mov es,ax 

MOV ah,49H 

call loc 50H 
endm = 


: FUNCTION REQUEST 4AH 
SET BLOCK macro last_byte 


mov bx,offset last byte 
mov cl,@ 

shr bx,cl 

inc bx 

mov ah, 4AH 

call loc 5SOH 

endm _ 


: FUNCTION REQUEST 4BH 
EXEC macro path,command,parms,function 


mov dx,offset path 
MOV bx,offset parms 
mov word ptr parms[02h],offset command 


Mov word ptr parms[(04h],cs 


MACRO DEFINITIONS 


mov 
call 
endm 


END PROCESS 
~ mov 
mov 
call 
endm 


WAIT macro 
mov 
call 
endm 


e 
4 


word ptr parms[06h]},5ch 
word ptr parms[08h],es 

word ptr parms[0Oah],6ch 
word ptr parms[Och],es 

al,function 

ah,4BH 

loc_50H 


FUNCTION REQUEST 
macro return code 
al,return code 
ah,4CH - 
loc_50H 


FUNCTION REQUEST 
ah, 4DH 
loc_50H 


FUNCTION REQUEST 


FIND FIRST FILE macro path,attrib 


mov 
mov 
mov 
call 
endm 


FIND NEXT FILE macro 


mov 
call 
endm 


GET VERIFY 
mov 
call 
endm 

RENAME FILE 
mov 
push 
POp 
mov 
mov 
call 
endm 


dx,offset path 
cx,attrib 

ah, 4EH 

loc_50H 


FUNCTION REQUEST 


ah, 4FH 
loc_50H 


FUNCTION REQUEST 
macro 
ah,54H 
loc_50H 


FUNCTION REQUEST 
macro old path,new path 
dx,offset old path ~ 
ds 7 
es 
di,offset new path 
ah,56H _ 
loc_50H 


FUNCTION REQUEST 


GET SET DATE TIME macro. handle,action,time,date 


mov 
mov 
mov 
mov 
mov 
call 


bx,handle 
al,action 
cx,word ptr time 
dx,word ptr date 
an,578 

loc_50H 
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4CH 


4DH 


4EH 


4FH 


54H 


56H 


57H 


MACRO DEFINITIONS 


endm 
; 
7 
eRRKKKKKKKKKKKKKK KKK 


> General 
eKREREKKEKEKKKEKKKEKKEKKE 


DISPLAY ASCIZ macro asciz string 
local search,found it 


mov bx,offset asciz string 
search: 

cmp byte ptr [bx],0 

je found it 

inc bx 


jmp short search 


found it: 


mov byte ptr [bx] ,"s" 
display asciz string 
Mov byte ptr [bx] ,0 


display char ODH 
display char OAH 
endm 


MOVE STRING macro’ source,destination,count 


push es 
push ds 
Pop es 
assume es:code 
mov si,offset source 
mov di,offset destination 
mov cx,count 
rep movs es:destination,source 
assume es:nothing 
pop es 
endm 


CONVERT macro value,base,destination 
local table,start 


jmp Start 
table db "0123456789ABCDEF" 
Start: 

push ax 

push bx 

push dx 

mov al,value 

XOX ah,ah 

XOX bx,bx 

div base 

mov cee es 

mov al,cs:table[bx] 

mov destination,al 


mov bl,ah 
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destination([1]),al 
ax 
Dx 
ax 


CONVERT TO BINARY macro’ string,number,value 


local 


jmp 
ten db 


ten,start,calc,mult,no mult 
Start 
10 


value,0O 
cx,cx 
cl,number 
Ssi,sl 


ax,ax 
al,string[si] 
al,48 

Cx,Z 

no mult 

cx 

Cx 


cs: ten 
mult 
Cx 


value,ax 
Si 
calc 


CONVERT DATE macro dir entry 


mov 
mov 
shr 
mov 
and 
XOr 
mov 
shr 
add 
endm 


dx,word ptr dir entry[24] 
e1,5 

at ei. 

Gh,dir entry[24] 

dh, 1FH > 

cx, cx 

cl,dir_entry([25] 

GL xl 

cx,1980 


PACK DATE macro date 
local set bit 


=e Se te 


sub 


On entry: 


DH=day, DL=month, CX=(year-1980) 


cx,1980 
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push cx 


mov date,dh 
mov el,5 
shl Gil ,eL 
pop ae 4 
jne Set bit 
Or cl1,80h 
Set bit: 

Or date,dl 
rol oat mf 
mov date[l],cl 


endm 
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CHAPTER 2 


MS-DOS 2.0 DEVICE DRIVERS 


2.1 WHAT IS A DEVICE DRIVER? 


A device driver is a binary file with all of the code in it 
to manipulate the hardware and provide a_e consistent 
interface to MS-DOS. In addition, it has a special header 
at the beginning that identifies it as a device, defines the 
Strategy and interrupt entry points, and describes various 
attributes of the device. 


NOTE 


For device drivers, the file 
must not use the ORG _ 100H 
(like .COM files). BecauSe it 


does not use the Program 
Segment Prefix, the device 
driver is Simply loaded; 


therefore, the file must have 
an Origin of zero (ORG 0 or no 
ORG statement). 


There are two kinds of device drivers. 


l. Character device drivers 


2. Block device drivers 


Character devices are designed to perform serial character 
I/O like CON, AUX, and PRN. These devices are named (i.e., 
CON, AUX, CLOCK, etc.), and users may open channels (handles 
or FCBs) to do I/O to them. 
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Block devices are the "disk drives" on the system. They can 
perform random I/O in pieces called blocks (uSually the 
physical sector size). These devices are not named as_ the 
character devices are, and therefore cannot be opened 
directly. Instead they are identified via the drive letters 
(A, B, GC, eter}. 


Block devices also have units. A Single driver may _ be 
responsible for one or more disk drives. For example, block 
device driver ALPHA may be responsible for drives A:,B:,C: 
and D:. This means that it has four units (0-3) defined 
and, therefore, takes up four drive letters. The position 
of the driver in the list of all drivers determines which 
units correspond to which driver letters. If driver ALPHA 
is the first block driver in the device list, and it defines 
“units (0-3), then they will be A:,B:,C: andD:. If BETA 
is the second block driver and defines three units (0-2), 
then they will be E:,F: and G:, and so on. MS-DOS 2.0 is 
not limited to 16 block device units, as were previous 
versions. The theoretical limit is 63 (26 = 1), bat it 
should be noted that after 26 the drive letters. are 
unconventional (such as ], \, and “). 


NOTE 


Character devices cannot 
define multiple units because 
they have only one name. 
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2.2 DEVICE HEADERS 


A device header is required at the beginning of a _ device 
driver. A device header looks like tnis: 


DWORD pointer to next device 
(Must be set to -1) 


WORD attributes 

Bit 15 = 1 if char device O is blk 

if Bit 15 is 2 
Bit if current sti device 
Bit 1f current sto output 
Bit = if current NUL device 
Bit = if current CLOCK dev 
Bit = if special 
Bits 5 Reserved; must be set 

ES © 
Bit 14 is the ITOCTL bit 
Bit 13 is the NON IBM FORMAT bit 


WORD pointer to device strategy 
entry point 

WORD pointer to device interrupt 
entry point 


8-BYTE character device name field 
Character devices set a device name. 
For block devices the first byte is 
the number cf units 





Figure 2.1. Sample Device Header 


Note that the device entry points are words. They must_ be 
offsets from the same segment number used to point to this 
table. For example, if XXX:YYY points to the start of this 
table, then XXX:strategy and XXX:interrupt are the entry 
points. 


2.2.1 Pointer To Next Device Pield 


The pointer to the next device header field is a double word 
field (offset followed by Segment) that is set by MS-DOS to 
point at the next driver in the system list at the time the 
device driver is loaded. It is important that this field be 
set to -l prior to load (when it is on the disk as ae file) 
unless there is more than one device driver in the file. If 
there iS more than one driver in the file, the first word of 
the double word pointer should be the offset of the next 
driver's Device Header. 
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NOTE 


If there iS more than one 
device driver in the .COM 
file, the last driver in the 
file must have the pointer to 
the next Device Header’ field 
set to -l. 


2.2.2 Attribute Pield 


The attribute field is used to tell the system whether this 
device is a block or character device (bit 15). Most other 
bits are used to give selected character devices certain 
special treatment. (Note that these bits mean nothing on a 
block device). For example, assume that a user hasS anew 
device driver that he wants to be the standard input and 
Output. Besides installing the driver, he must tell MS-DOS 
that he wants his new driver to override the current 
Standard input and Standard output (the CON’ device). This 
is accomplished by setting the attributes to the desired 


characteristics, so he would set bits 0 and 1 to 1 £(note 
that they are sSeparate!). Similarly, a new CLOCK device 
could be installed by setting that attribute. (Refer to 


Section 2.7, "The CLOCK Device," in this chapter for more 
information.) Although there is a NUL device attribute, the 
NUL device cannot be reassigned. This attribute exists so 
that MS-DOS can determine if the NUL device is being used. 


The NON IBM FORMAT bit applies only to block devices and 
affects the operation of the BUILD BPB (BIOS Parameter 
Block) device call. (Refer to Section 2.5.3, “MEDIA CHECK 
And BUILD BPB," for further information on this call). 


The other bit of interest is the IOCTL bit, which has 
meaning on character and block devices. This bit tells 
MS-DOS whether the device can handle control strings (via 
the IOCTL system call, Function 44H). 


If a driver cannot process control strings, it should 
initially set this bit to 0. This tells MS-DOS to return an 
error if an attempt is made (via Function 44H) to send _ or 
receive control strings to this device. A device which can 
process control strings should initialize the IOCTL bit to 
Ls For drivers of this type, MS-DOS will make calls to the 
IOCTL INPUT and OUTPUT device functions to send and receive 
IOCTL strings. 


The IOCTL functions allow data to be sent and received by 
the device for its own use (for example, to set baud rate, 
stop bits, and form length), instead of passing data over 
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the device channel as does a normal read or write. The 
interpretation of the passed information is up to the 
device, but it must not be treated as a normal I/O request. 


2.2.3 Strategy And Interrupt Routines 


These two fields are the pointers to the entry points df the 
Strategy and interrupt routines. They are word values, so 
they must be in the same segment as the Device Header. 


2.2.4 Name Field 


This is an 8-byte field that contains the name of a 
character device or the number of units of a block device. 
If it is a block device, the number of units can be put in 
the first byte. This is optional, because MS-DOS will fill 
in this location with the value returned by the driver's 
INIT code. Refer to Section 2.4, "Installation of Device 
Drivers" in this chapter for more information. 


2.3 HOW TO CREATE A DEVICE DRIVER 


In order to create a device driver that MS-DOS can install, 
you must write ae binary file with a Device Header at the 
beginning of the file. Note that for device drivers, the 
code should not be originated at 1lOOH, but rather at 0. The 
link field (pointer to next Device Header) should be -l, 
unless there 1S more than one device driver in the file. 
The attribute field and entry points must be set correctly. 


If it is a character device, the name field should be filled 
in with the name of that character device. The name can be 
any legal 8-character filename. 


MS-DOS always processes installable device drivers’ before 
handling the default devices, so to install a new CON 
device, simply name the device CON. Remember to set’ the 
standard input device and standard output device bits in the 
attribute word on a new CON device. The scan of the device 
list stops on the first match, so the installable device 
driver takes precedence. 
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NOTE 


Because MS-DOS can install the 
driver anywhere in memory, 
Care must be taken in any far 
memory references. You should 
not expect that your. driver 
will always be loaded in the 
Same place every time. 


2.4 INSTALLATION OF DEVICE DRIVERS 


MS-DOS 2.0 allows new device drivers to be installed 
dynamically at boot time. This is accomplished by INIT code 
in the BIOS, which reads and processes the CONFIG.SYS file. 


MS-DOS calls upon the device drivers to perform their 
function in the following manner: 


MS-DOS makes a far call to strategy entry, and 
passes (in a Request Header) the information 
describing the functions of the device driver. 


This structure allows you to program an_e interrupt-driven 
device driver. For example, you may want to perform local 
buffering in a printer. 


2.5 REQUEST HEADER 


When MS-DOS calls a device driver to perform a function, it 
passes a Request Header in ES:BX to the strategy entry 
point. This is a fixed length header, followed by data 
pertinent to the operation being performed. Note that it is 
the device driver's responsibility to preserve the machine 
state (for example, save all registers on entry and restore 
them on exit). There is enough room on the _ stack when 
strategy or interrupt is called to do about 20 pushes. If 
more stack is needed, the driver should set up itS = own 
Stack. 
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The following figure illustrates a Request Header. 


REQUEST HEADER ~> 


BYTE length of record 
Length in bytes of this 
Request Header 


BYTE unit code 

The Subunit the operation 
is for (minor device) 

(nO meaning on character 


devices) 


BYTE command code 


WORD status 


8 bytes RESERVED 





Figure 2.2. Request Header 


2.5.1 Unit Code 


The unit code field identifies which unit in your. device 
driver the request is- for. For example, if your device 
driver has 3 units defined, then the possible values of the 
unit code field would be O, 1, and 2. 


2.5.2 Command Code Pield 


The command code field in the Request header can have the 
following values: 


Command Function 
Code 


INIT 

MEDIA CHECK (Block only, NOP for character) 
BUILD BPB " Ww iT " Ww 

IOCTL INPUT (Only called if device has IOCTL) 
INPUT (Read) 

NON-DESTRUCTIVE INPUT NO WAIT (Char devs only) 
INPUT STATUS 4s : ci 
INPUT FLUSH e 7 ? 
OUTPUT (Write) 

OUTPUT (Write) with verify 

10 OUTPUT STATUS ‘ ‘i 
ll OUTPUT FLUSH i " . 
ie, IOCTL OUTPUT (Only called if device has IOCTL) 


OD NNN &WDN bF O 
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2.5.3 MEDIA CHECK And BUILD BPB 


MEDIA CHECK and BUILD BPB are used with block devices only. 


MS-DOS calls MEDIA CHECK first for a drive unit. MS-DOS 
passes itS current media descriptor byte (refer to the 
section "Media Descriptor Byte" later in this chapter). 
MEDIA CHECK returns one of the following results: 


Media Not Changed - current DPB and media byte are 
OK. 


Media Changed - Current DPB and media are wrong. 
MS-DOS invalidates any buffers for this unit and 
calls the device driver to build the BPB with media 
byte and buffer. 


Not Sure - If there are dirty buffers (buffers with 
changed data, not yet written to disk) for this 
unit, MS-DOS assumes the DPB and media byte are OK 
(media not changed). If nothing is dirty, MS-DOS 
assumes the media has changed. It invalidates any 
buffers for the unit, and calls the device driver 
to build the BPB with media byte and buffer. 


Error - If an error occurs, the driver sets: the 
error code accordingly. 


MS-DOS will call BUILD BPB under the following conditions: 
If Media Changed is returned 


If Not Sure is returned, and there are no dirty 
buffers 


The BUILD BPB call also getsS a pointer to a one-sector 
buffer. What this buffer contains is determined by the NON 
IBM FORMAT bit in the attribute field. If the bit is zero 
(device is IBM format-compatible), then the buffer contains 
the first sector of the first FAT. The FAT ID byte is_~ the 
first byte of this buffer. NOTE: The BPB must be the same, 
as far as location of the FAT is concerned, for all possible 
media because this first FAT sector must be read before the 
actual BPB is returned. If the NON IBM FORMAT bit is_- set, 
then the pointer points to one_ sector of Scratch space 
(which may be used for anything). 


MS-DOS 2.0 DEVICE DRIVERS Page 2-9 


2.5.4 Status Word 


The following figure illustrates the status word in the 
Request Header. 


15 1413121110 9 8 7 &@ &@ 4@ 3 #2 ff OQ 


RESERVED ERROR CODE (bit 15 on) 





The status word is zero on entry and is set by the driver 
interrupt routine on return. 


Bit 8 is the done bit. When set, it means the operation 1S 
complete. For MS-DOS 2.0, the driver sets it to 1 when it 
exits. 


Bit 15 is the error bit. If it iS set, then the low 8 bits 
indicate the error. The errors are: 


Write protect violation 
Unknown Unit 

Drive not ready 

Unknown command 

CRC error 

Bad drive request structure length 
Seek error 

Unknown media 

Sector not found 
Printer out of paper 
Write fault 

Read Fault 

General failure 


AWPOWIMAMNAVNUMPWNFO 


Bit 9 is the busy bit, which is set only by status calls. 


For output on character devices: If bit 9 is l on 
return, a write request (if made) would wait for 
completion of a current request. If it is 0, there 
is no current request, and a write request (if 
made) would start immediately. 
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For input on character devices with a buffer: i 
bit 9 is 1 on return, a read request (if made) 
would go to the physical device. If it is 0 on 
return, then there are characters in the device 
buffer and a read would return = quickly. It also 
indicates that something has been typed. MS-DOS 
assumes all character devices’. have an input 
type-ahead buffer. Devices that do not have a 


type-ahead buffer should always return busy=0 = so 
that MS-DOS will not continuously wait for 
something to get into a buffer that does not exist. 


One of the functions defined for each device is INIT. This 
routine is called only once when the device is installed. 
The INIT routine returns the BREAK ADDRESS, which is a DWORD 
pointer to the first free byte in memory. This pointer 
method can be used to delete initialization code that is 
only needed once, Saving on space. 


Block devices are installed this way and return a first free 


byte pointer as described above. Additional information is 
also returned: 


The number of units is returned. This determines 
logical device names. If the current maximum 
logical device letter is F at the time of the 
install call, and the INIT routine returns 4 as the 
number of units, then they will have logical names 
G, H, I and J. This mapping is determined by the 
position of the driver in the device list, and _ by 
the number of units on the device (stored in the 
first byte of the device name field). 


A pointer to a BPB (BIOS Parameter Block) pointer 
array is also- returned. There is one table for 
each unit defined. These blocks will be used _ to 
build an internal DOS data structure for each of 
the units. The pointer passed to the DOS from the 
driver points to an array of n word pointers to 
BPBs, where n is the number of units defined. In 
this way, if all units are the same, all of the 
pointers can point to the same BPB, saving- space. 
Note that this array must be protected (below the 
free pointer set by the return) Since an_ internal 
DOS structure will be built starting at the byte 
pointed to by the free pointer. The sector size 
defined must be less than or equal to the maximum 
sector size defined at default BIOS INIT time. If 
it isn't, the install will fail. 
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The last thing that INIT of a block device must 
pass back 1s the media descriptor byte. This byte 
means nothing to MS-DOS, but 1S passed to devices 
SO that they know what parameters MS-DOS is 
currently uSing for a particular drive unit. 


Block devices may take Several approaches; they may be dumb 


Or smart. A dumb device defines a unit (and therefore an 
internal DOS structure) for each possible media drive 
combination. For example, unit 0 = drive O single side, 
unit 1 = drive 0 double side. For this approach, media 
descriptor bytes do not mean anything. A smart device 
allows multiple media per unit. In this case, the BPB table 
returned at INIT must define space large enough to 
accommodate the largest possible media supported. Smart 
drivers will use the media descriptor byte to pass 


information about what media is currently ina unit. 


2.6 FUNCTION CALL PARAMETERS 


All strategy routines are called with ES:BX pointing to’ the 
Request Header. The interrupt routines get the pointers to 
the Request Header from the queue that the strategy routines 
store them in. The command code in the Request Header tells 
the driver which function to perform. 


NOTE 


All DWORD pointers are stored 
offset first, then segment. 
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2.6.1 INIT 


Command code = 0 


INIT = ES:BA => 


13-BYTE Request Header 
BYTE # of units 
DWORD break address 


DWORD pointer to BPB array 
(Not set by character devices) 


The number of units, break address, and BPB pointer are set 
by the driver. On entry, the DWORD that is to be set to the 
BPB array (on block devices) points to the character after 
the ‘=' on the line in CONFIG.SYS that loaded this device. 
This allows drivers to scan the CONFIG.SYS invocation line 
for arguments. 







NOTE 


If there are multiple device 
drivers in a Single .COM file, 
the ending address returned by 
the last INIT called will be 
the one MS-DOS uses. re 2s 
recommended that all of the 
device drivers in a_ single 
-COM file return the same 
ending address. 


2.6.2 MEDIA CHECK 


Command Code = lL 


MEDIA CHECK - ES:BX -> 
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In addition to setting the status word, the driver must set 
the return byte to one of the following: 


-1 Media has been changed 
0 Don't know if media has been changed 
1 Media has not been changed 


If the driver can return -l or 1 (by having a door-:--lock or 
other interlock mechanism) MS-DOS performance is enhanced 
because MS-DOS does not need to reread the FAT for- each 
directory access. 


2.6.3 BUILD BPB (BIOS Parameter Block) 


Command code = 2 


BUILD BPB - ES:BX <-> 


DWORD transfer address 
(Points to one sector worth of 


scratch space or first sector 
of FAT depending on the value 
of the NON IBM FORMAT bit) 


DWORD pointer to BPB 





If the NON IBM FORMAT bit of the device iS set, then’ the 
DWORD transfer address points to a one sector buffer, which 
can be used for any purpose. If the NON IBM FORMAT bit is 
0, then this buffer contains the first sector of the first 
FAT and the driver must not alter this buffer. 


If IBM compatible format is used (NON IBM FORMAT BIT = 0), 
then the first sector of the first FAT must be located at 
the same sector on all possible media. This is because the 
FAT sector will be read BEFORE the media is actually 
determined. Use this mode if all you want is to read_ the 
FAT ID byte. 


In addition to setting status word, the driver must set’ the 
Pointer to the BPB on return. 
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In order to allow for many different OEMS to read_ each 
other's disks, the following standard is suggested: The 
information relating to the BPB for a particular piece of 
media is kept in the boot sector for the media. In 
particular, the format of the boot sector is: 


3 BYTE near JUMP to boot code 

8 BYTES OEM name and version 
WORD bytes per sector 

BYTE sectors per allocation unit 


WORD reserved sectors 


— wvovwD 


BYTE number of FATS 
WORD number of root dir entries 


WORD number of sectors in logical 
image 


BYTE media descriptor 


WU WC > 


WORD number of FAT sectors 
WORD sectors per track 
WORD number of heads 


WORD number of hidden sectors 





The three words at the end (sectors per track, number of 
heads, and number of hidden sectors) are optional. They are 
intended to help the BIOS understand the media. Sectors per 
track may be redundant (could be calculated from total size 
of the disk). Number of heads is useful for supporting 
different multi-head drives which have the same storage 
capacity, but different numbers of surfaces. Number of 
hidden sectors may be used to Support drive-partitioning 
schemes. 
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2.6.4 Media Descriptor Byte 


In MS-DOS 2.0, the media descriptor byte identifies 
different media. The media descriptor byte can be any value 
between 0 and FFH. It does not have to be the Same as_ the 
FAT ID byte. The FAT ID byte, which is the first byte of 
the FAT, was used in MS-DOS 1.0 to determine the disk media 
and may be used as well under 2.0 disk device drivers. 
However, FAT ID bytes only have’ significance for IBM 
format-compatible block device drivers. 


Currently, the media descriptor byte has been defined for a 
few media types, including 5-1/4" and 8" standard disks. 
For more information, refer to Section 3.6, "MS-DOS Standard 
Disk Formats." 
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2.6.5 READ Or WRITE 


Command codes = 3,4,8,9, and 12 


READ Or WRITE - ES:BX (Including IOCTL) -> 


WORD starting sector number 
(Ignored on character devices) 


In addition to setting the status word, the driver must set 
the sector count to the actual number of sectors (or bytes) 
transferred. No error check is performed on an IOCTL I/O 
call. The driver must always correctly set the return 
sector (byte) count to the actual number of bytes 
transferred. 











THE FOLLOWING APPLIES TO BLOCK DEVICE DRIVERS: 
Under certain circumstances the BIOS may be asked to perform 
a write operation of 64K bytes, which seems to be a "wrap 
around" of the transfer address in the BIOS I/O packet. 
This request arises due to an optimization added to the 
write code in MS-DOS. It will only manifest on user writes 
that are within a sector size of 64K bytes on files 

"growing™ past the current EOF. It is allowable for the 
BIOS to ignore the balance of eS write that “wraps around" 


it 3 = pie For example, a write of 10000H bytes 
worth of sectors with a Ceres address of XXX:1l could 


ignore on last two bytes. A user program can never request 
an I/O of more than FFFFH bytes and cannot wrap around (even 
to 0) in the transfer segment. Therefore, in this case, the 
last two bytes can be ignored. 
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2.6.6 NON DESTRUCTIVE READ NO WAIT 


Command code = 5 


NON DESRUCTIVE READ NO WAIT - ES:BX -> 


13-BYTE Request Header 
BYTE read from device 





If the character device returns busy bit = 0 (characters in 
buffer), then the next character that would be read is 
returned. This character is not removed from the input 


buffer (hence the term "Non Destructive Read"). Basically, 
this call allows MS-DOS to look ahead one input character. 
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2aGal 


STATUS 


Command codes = 6 and 10 


STATUS Calls - ES:BX -> 


13-BYTE Request Header 


All the driver must do is set the status word and the busy 
bit as follows: 


For Output on character devices: If bit 9 is 1 on 
return, a write request (if made) would wait for 
completion of a current request. If it is 0, there 
is no current request and a write request (if made) 


would start immediately. 


For input on character devices with a _ buffer: A 
return of 1 means, a read request (if made) would 
go to the phySical device. If it is 0 on return, 


then there are characters in the devices buffer and 
a read would return quickly. A return of 0 also 
indicates that the user has typed something. 
MS-DOS assumes that all character devices have an 
input type-ahead buffer. Devices that do not have 
a type-ahead buffer should always return busy = 0 
so that the DOS will not hang waiting for something 
to get into a buffer which doesn't exist. 


2.6.8 FLUSH 


Command codes = 7 and ll 


FLUSH Calls - ES:BX -> 


13-BYTE Request Header 


The FLUSH call tells the driver to flush (terminate) all 


pending 


requests. This call is used to flush the input 


queue on character devices. 
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2.7 THE CLOCK DEVICE 


One of the most popular add-on boards is the real time clock 
board. To allow this board to be integrated into the system 
for TIME and DATE, there 1S a Special device (determined by 
the attribute word), called the CLOCK device. The CLOCK 
device defines and performs functions like = any other 
character device. Most functions will be: "Set done bit, 
reset error bit, return." When a read or write to this 
device occurs, exactly 6 bytes are transferred. The first 
two bytes are a word, which is the count of days since 
1-1-80. The third byte is minutes; the fourth, hours; the 
fifth, hundredths of seconds; and the sixth, seconds. 
Reading the CLOCK device gets the date and time; writing to 
it sets the date and time. 


ho 
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2.8 EXAMPLE OF DEVICE DRIVERS 


The following examples illustrate a block device driver and 
a character device driver program. 


2.8.1 Block Device Driver 


sREKKKKEKKKKKKEKKKKKEKKEKEK A BLOCK DEVICE *¥®®® kk KKKKKKKKKKEKEK 


TITLE 5 1/4" DISK DRIVER FOR SCP DISK-MASTER 


sThis driver is intended to drive up to four 5 1/4" drives 
shooked to the Seattle Computer Products DISK MASTER disk 
scontroller. All standard IBM PC formats are Supported. 


FALSE EQU 0 

TRUE EQU NOT FALSE 
sThe I/O port address of the DISK MASTER 
DISK EQU OEOH 
*DISK+0 

: 1793 Command/Status 
>DISK+1 

; 1793 Track 
s;DISK+2 

H LT33 Sector 
;DISK+3 

: 1793 Data 
;DISK+4 

: Aux Command/Status 
*>DISK+5 

; Wait Sync 

*Back side select bit 
BACKBIT EQU 04H 

75 1/4" select bit 

SMALBIT EQU 10H 
;Double Density bit 

DDBIT EQU 08H 


»Done bit in status register 
DONEBIT EQU 01H 


;Use table below to select head step speed. 
sStep times for 5" drives 

sare double that shown in the table. 

;Step value 1771 1793 


0 6ms 3ms 
i 6ms 6ms 


=e “SO sO 
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: 2 10ms 10ms 
: 3 20ms 15ms 
STPSPD EQU 1 
NUMERR EQU ERROUT-ERRIN 
CR EQU ODH 
LF EQU OAH 
CODE SEGMENT 
ASSUME CS:CODE,DS:NOTHING, ES:NOTHING,SS:NOTHING 
; DEVICE HEADER 
DRVDEV LABEL WORD 
DW -l,-l 
DW 0000 >IBM format-compatible, Block 
DW STRATEGY 
DW DRVSIN 
DRVMAX DB 4 
DRVTBL LABEL WORD 
DW DRVSINIT 
DW MEDIASCHK 
DW GETSBPB 
DW CMDERR 
DW DRVS$ READ 
DW EXIT 
DW EXIT 
DW EXIT 
DW DRVSWRIT 
DW DRVSWRIT 
DW EXIT 
DW EXIT 
DW EXIT 
: STRATEGY 
PTRSAV DD 0 
STRATP PROC FAR 
STRATEGY: 
MOV WORD PTR [PTRSAV] ,BX 
MOV WORD PTR [PTRSAV+2],ES 
RET 


STRATP ENDP 
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CMDLEN = 0 ; LENGTH OF THIS COMMAND 
UNIT = i ;SUB UNIT SPECIFIER 
CMDC = 2 ;COMMAND CODE 
STATUS = 3 ;STATUS 
MEDIA = Ls s;MEDIA DESCRIPTOR 
TRANS = 14 ; TRANSFER ADDRESS 
COUNT = 18 COUNT OF BLOCKS OR CHARACTERS 
START = 20 ;FIRST BLOCK TO TRANSFER 
DRVSIN: 
PUSH SI 
PUSH AX 
PUSH CX 
PUSH DX 
PUSH DI 
PUSH BP 
PUSH DS 
PUSH ES 
PUSH BX 
LDS BX, [PTRSAV] *>GET POINTER TO I/O PACKET 
MOV AL,BYTE PTR [BX].UNIT sAL = UNIT CODE 
MOV AH,BYTE PTR [BX] .MEDIA >AH = MEDIA DESCRIP 
MOV CX,WORD PTR [BX] .COUNT :CX = COUNT 
MOV DX,WORD PTR [BX].START *DX = START SECTOR 
PUSH AX 
MOV AL,BYTE PTR [BX] .CMDC Command code 
CMP AL,11 
JA CMDERRP >Bad command 
CBW 
SHL AX,1 7:2 times command = 
;word table index 
MOV SI,OFFSET DRVTBL 
ADD SI,AX ;Index into table 
POP AX ;Get back media 
sand unit 
LES DI,DWORD PTR [BX].TRANS ;ES:DI = TRANSFER 
;ADDRESS 
PUSH CS 
POP DS 
ASSUME DS:CODE 
JMP WORD PTR [SI} ;GO DO COMMAND 


EXIT - ALL ROUTINES RETURN THROUGH THIS PATH 


ASSUME DS:NOTHING 
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POP AX sClean stack 
CMDERR: 
MOV AL, 3 > UNKNOWN COMMAND ERROR 
JMP SHORT ERRSEXIT 
ERRSCNT: LDS BX, [PTRSAV] 
SUB WORD PTR [BX].COUNT,CX ;# OF SUCCESS. I/Os 
ERRSEXIT: 
s;AL has error code 
MOV AH, 10000001B *>MARK ERROR RETURN 
JMP SHORT ERRIL 
EXITP PROC FAR 
EXLT: MOV AH,00000001B 
ERR1: LDS BX, [PTRSAV] 
MOV WORD PTR [BX] .STATUS,AX 
;MARK OPERATION COMPLETE 
POP BX 
POP ES 
POP DS 
POP BP 
POP DI 
POP DX 
POP CX 
POP AX 
POP SI 
RET sRESTORE REGS AND RETURN 
EXITP ENDP 
CURDRV DB -l 
SECCNT DW 0 
DRVLIM = 8 sNumber of sectors on device 
SECLIM = is ;MAXIMUM SECTOR 
HDLIM = 15 >MAXIMUM HEAD 


s;WARNING - preserve order of drive and curhd! 


DRIVE DB 0 ;PHYSICAL DRIVE CODE 
CURHD DB 0 ; CURRENT HEAD 
CURSEC DB 0 ;CURRENT SECTOR 
CURTRK DW 0 ;CURRENT TRACK 
MEDIASCHK: ;Always indicates Don't know 
ASSUME DS:CODE 
TEST AH,00000100B ;TEST IF MEDIA REMOVABLE 


JZ MEDIASEXT 


MS-DOS 2.0 DEVICE DRIVERS 


XOR 


MEDIASEXT: 


LDS 
MOV 
JMP 


BUILDSBPB: 


ASSUME 


SETBPB: 


BUILDBP: 


DS : CODE 


DI,DI 
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;SAY I DON'T KNOW 


BX, [PTRSAV] 
WORD PTR [BX].TRANS,DI 


EXIT 


AH,BYTE PTR ES: [DI] 


BUILDBP 


;GET FAT ID BYTE 
; TRANSLATE 


BX, [PTRSAV] 

[BX] .MEDIA,AH 
[BX] .COUNT,DI 
[BX] .COUNT+2,CS 


EXIT 


ASSUME DS:NOTHING 
;AH is media byte on entry 
;DI points to correct BPB on return 


GOODID: 


HAS8: 


HAS 1: 


PUSH 


AX 
CX 
DX 
BX 
CL,AH ;SAVE MEDIA 
CL,OF8H ; NORMALIZE 
CL,OF8H ; COMPARE WITH GOOD MEDIA BYTE 
GOODID 
AH, OFEH ;DEFAULT TO 8-SECTOR, 
; SINGLE-SIDED 
AL, 1 ;SET NUMBER OF FAT SECTORS 
BX,64*256+8 ;SET DIR ENTRIES AND SECTOR MAX 
CxX,40*8 ;SET SIZE OF DRIVE 
DX,01*256+1 ;SET HEAD LIMIT & SEC/ALL UNIT 


DI,OFFSET DRVBPB 
AH,00000010B ;TEST FOR 8 OR 9 SECTOR 


HAS8 ;NZ = HAS 8 SECTORS 

AL ; INC NUMBER OF FAT SECTORS 
BL 7; INC SECTOR MAX 

CX, 40 ; INCREASE SIZE 
AH,00000001B ;TEST FOR 1 OR 2 HEADS 
HAS1 ;Z = 1 HEAD 

CX ,CX ;DOUBLE SIZE OF DISK 
BH,112 ; INCREASE # OF DIREC. ENTRIES 
DH ;INC SEC/ALL UNIT 

DL ; INC HEAD LIMIT 

BYTE PTR [DI]).2,DH 

BYTE PTR [DI] .6,BH 

WORD PTR [DI] .8,CX 

BYTE PTR [DI]).10,AH 

BYTE PTR [DI].11,AL 

BYTE PTR [DI).13,BL 

BYTE PTR [DI].15,DL 
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POP DX 
POP CX 
POP AX 
RET 
: DISK I/O HANDLERS 
: ENTRY: 
° AL = DRIVE NUMBER (0-3) 
. AH = MEDIA DESCRIPTOR 
H CX = SECTOR COUNT 
° DX = FIRST SECTOR 
: DS = CS 
: ES:DI = TRANSFER ADDRESS 
eEAILT: 
: IF SUCCESSFUL CARRY FLAG = 0 
. ELSE CF=l1 AND AL CONTAINS (MS-DOS) ERROR CODE, 
CX # sectors NOT transferred 
DRVS$ READ: 
ASSUME DS:CODE 
JCXZ DSKOK 
CALL SETUP 
JC DSKSIO 
CALL DISKRD 
JMP SHORT DSKSIO 
DRVSWRIT: 
ASSUME DS:CODE 
JCXZ DSKOK 
CALL SETUP 
JC DSKSIO 
CALL DISKWRT 
ASSUME DS:NOTHING 
DSKS$SIO: JNC DSKOK 
JMP ERRSCNT 
DS KOK: JMP EXIT 
SETUP: 


ASSUME DS:CODE 

;Input same as above 

7O0n output 

ES:DI = Trans addr 

DS:BX Points to BPB 

Carry set if error (AL is error code (MS-DOS) ) 
else 


=e Oe =O ZO VO BVH BVO VO WE 


[DRIVE] = Drive number (0-3) 

[SECCNT] = Sectors to transfer 

[CURSEC] = Sector number of start of I/0 

[CURHD] = Head number of Start of I/0 7Set 
[CURTRK] = Track # of start of I/O ;Seek performed 
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; All other registers destroyed 


INRANGE: 


SEEK: 


TRYSK: 


NOHOME : 


BX,DI 7;ES:BX = TRANSFER ADDRESS 
BUILDBP 7DS:DI = PTR TO B.P.B 
SI,CX 

SI,DX 


, 
SI,WORD PTR [DI].DRVLIM 
;COMPARE AGAINST DRIVE MAX 
INRANGE 
AL, 8 


[DRIVE] , AL 


[SECCNT] ,CX ;SAVE SECTOR COUNT 

AX,DX ;SET UP LOGICAL SECTOR 
;FOR DIVIDE 

DX,DX 


WORD PTR [DI].SECLIM ;DIVIDE BY SEC PER TRACK 
DL 


[CURSEC] ,DL *;SAVE CURRENT SECTOR 
CX,WORD PTR [DI].HDLIM ;GET NUMBER OF HEADS 
DX ,DX ;DIVIDE TRACKS BY HEADS PER CYLINDER 
CX 

[{CURHD] ,DL ;SAVE CURRENT HEAD 

[CURTRK] ,AX ;SAVE CURRENT TRACK 

BX ;Xaddr 

DI ;BPB pointer 

CHKNEW Unload head if change drives 
DRIVESEL 

BL, [DRIVE] 

BH, BH *>BX drive index 

BX,OFFSET TRKTAB ;Get current track 
AX, [CURTRK] 

DL,AL Save desired track 

AL,DS: [BX] sMake desired track current 
DISK+1,AL Tell Controller current track 
AL,DL ;At correct track? 

SEEKRET >Done if yes 

BH, 2 ;Seek retry count 

AL,-l :;Position Known? 

NOHOME :;If not home head 

HOME 

SEEKERR 

AL, DL 

DISK+3,AL *Desired track 

AL, 1CH+STPSPD ;Seek 

DCOM 

AL, 98H ;Accept not rdy, seek, & CRC errors 
SEEKRET 


SEEKERR ;No retries if not ready 


MS-DOS 2.0 DEVICE DRIVERS 


SEEKERR: 


SEEKRET: 


BH 
TRYSK 


BL, [DRIVE] 
BH, BH 


BX,OFFSET TRKTAB 
BYTE PTR DS: (BX],-1 


GETERRCD 
CX, [SECCNT] 
BX 

DI 


BX 
DI 


Page 2-27 


>BX drive index 
>Get current track 


;Make current track 
;unKnown 


sNothing transferred 
;BPB pointer 
;Xaddr 


;BPB pointer 
>Xaddr 


DISKRD: 


ASSUME DS:CODE 


RDLP : 


STOSB 


IN 


CX, [SECCNT] 


PRESET 

BX 

BL,10 

DX ,DISK+3 


AL, 80H 


DISK,AL 
BP,DI 


SHORT RLOOPENTRY 


AL,DISK+5 
AL, 1 
AL,DX 
RLOOP 


GETSTAT 


;Retry count 
;Data port 


;Read command 
;Disable for 1793 


;Output read command 
;Save address for retry 


;Wait for DRQ or INTRQ 
;Read data 
sInts OK now 


:Ok 
;Get back transfer 


;Record not found? 
;NO 
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;Map it 


MOV AL, 1 
GOT CODE: 
= CALL GETERRCD 
POP BX 
RET 
RDPOP: 
POP BX 
LOOP RDLP 
CLC 
RET 
: WRITE 
DISKWRT: 
ASSUME DS:CODE 
MOV CX, [SECCNT ]} 
MOV SI ,DI 
PUSH ES 
POP DS 
ASSUME DS:NOTHING 
WRLP: 
CALL PRESET 
PUSH BX 
MOV BL, 10 
MOV DX ,DISK+3 
WRAGN : 
MOV AL,OAOH 
CLI 
OUT DISK,AL 
MOV BP,SI 
WRLOOP : 
IN AL,DISK+5 
SHR AL,l 
LODSB 
OUT DX,AL 
JNC WRLOOP 
Srl 
DEC SI 
CALL GETSTAT 
AND AL, OFCH 
JZ WRPOP 
MOV SI,BP 
DEC BL 
JINZ WRAGN 
CALL GETERRCD 
POP BX 
RET 
WRPOP: 
POP BX 


;Retry count 
;Data port 


;Write command 

;Disable for 1793 
;Output write command 
;Save address for retry 


>Get data 
sWrite data 


s;Ints OK now 


*Ok 
>Get back transfer 
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PRESET: 
ASSUME 


STEP: 
ASSUME 


HOME : 
ASSUME 
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*Select new head 
*Go on to next track 
:Select head zero 


*First sector 
»>Reset CURSEC 


Tell controller which sector 
;We go on to next sector 


;Step in w/ update, no verify 


*BX drive index 
;Get current track 
>Next track 


;Restore with verify 


;No retries if not ready 
;Save real error code 
;Step in w/ update no verify 


;Get back real error code 


LOOP WRLP 
CLC 

RET 

DS :NOTHING 

MOV AL, [CURSEC] 

CMP AL,CS: [BX] .SECLIM 
JBE GOTSEC 

MOV DH, [CURHD] 

INC DH 

CMP DH,CS: [BX] .HDLIM 
JB SETHEAD 

CALL STEP 

XOR DH , DH 

MOV [CURHD] , DH 

CALL DRIVESEL 

MOV AL, 1 

MOV [CURSEC] , AL 

OUT DISK+2,AL 

INC [CURSEC] 

RET 

DS : NOTHING 

MOV AL,58H+STPSPD 
CALL DCOM 

PUSH BX 

MOV BL, [DRIVE] 

XOR BH,BH 

ADD BX,OFFSET TRKTAB 
INC BYTE PTR CS: [BX] 
POP BX 

RET 

DS : NOTHING 

MOV BL, 3 

MOV AL,OCH+STPSPD 
CALL DCOM 

AND AL, 98H 

JZ RET3 

JS HOMERR 

PUSH AX 

MOV AL,58H+STPSPD 
CALL DCOM 

DEC BL 

POP AX 

JINZ TRYHOM 
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RET 3: RET 


CHKNEW: 


ASSUME DS:NOTHING 


AL, [DRIVE] ;Get disk drive number 
AH,AL 

AL, [CURDRV] ;Make new drive current. 
AL,AH ;Changing drives? 

RET1 :;No 


; If changing drives, unload head so the head load delay 
;one-Shot will fire again. Do it by seeking to the same 
strack with the H bit reset. 


e 
’ 


IN 
OUT 
MOV 


DCOM : 


AL, DISK+1 ;Get current track number 
DISK+3,AL *sMake it the track to seek 
AL, 10H :Seek and unload head 


ASSUME DS:NOTHING 


OUT 


GETSTAT: 


RET 1: RET 


DRIVESEL: 


DISK,AL 
AX 

;Delay 10 microseconds 
AX 


AL,DISK+4 
AL,DONEBIT 
GETSTAT 
AL,DISK 


ASSUME DS:NOTHING 
>Select the drive based on current info 
;Only AL altered 


MOV 


GETERRCD: 


AL, [DRIVE] 


AL,SMALBIT + DDBIT >5 1/4" IBM PC disks 
{CURHD] ,0 

GOTHEAD 

AL,BACKBIT >Select side 1 

DISK+4,AL Select drive and side 


ASSUME DS:NOTHING 


PUSH 


CX 

ES 

DI 

Co 

ES ;Make ES the local segment 
CS: [LSTERR] ,AL ;Terminate list w/ error code 
CX ,NUMERR sNumber of error conditions 
DI,OFFSET ERRIN ;Point to error conditions 
SCASB 


MS-DOS 2.0 DEVICE DRIVERS Page 2-31 


MOV AL,NUMERR-l1[DI] ;Get translation 

STc >Flag error condition 
POP DI 

POP ES 

POP CX 

RET sand return 


om waa KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KK KKK KKK KKK KKK KR KKK KRKKKK 
‘ 


: BPB FOR AN IBM FLOPPY DISK, VARIOUS PARAMETERS ARE 
PATCHED BY BUILDBP TO REFLECT THE TYPE OF MEDIA 
INSERTED 

This is a nine sector Single side BPB 


=e =e Me 


DRVBPB: 
DW oa We. *PhySical sector size in bytes 
DB 1 *Sectors/allocation unit 
DW 1] ;Reserved sectors for DOS 
DB 2 ># of allocation tables 
DW 64 ;Number directory entries 
DW 9*40 ;Number 512-byte sectors 
DB 11111100B ;Media descriptor 
DW 2 s-Number of FAT sectors 
DW 9 ;Sector limit 
DW 1 s;Head limit 
INITAB DW DRVBPB ;Up to four units 
DW DRVBPB 
DW DRVBPB 
DW DRVBPB 
ERRIN: ;DISK ERRORS RETURNED FROM THE 1793 CONTROLER 
DB 80H ;NO RESPONSE 
DB 40H ;Write protect 
DB 20H ;Write Fault 
DB 10H ;SEEK error 
DB 8 CRC error 
DB 1 ;Mapped from 10H 
;(record not found) on READ 
LSTERR- DB 0 >ALL OTHER ERRORS 
ERROUT: ;RETURNED ERROR CODES CORRESPONDING TO ABOVE 
DB 2 ;NO RESPONSE 
DB 0 ;WRITE ATTEMPT 
ON WRITE-PROTECT DISK 
DB OAH ;WRITE FAULT 
DB 6 *>SEEK FAILURE 
DB 4 BAD CRC 
DB 8 *>SECTOR NOT FOUND 
DB 12 GENERAL ERROR 
DRVSINIT: 


Determine number of physical drives bv reading CONFIG.SYS 


=e "Se me 
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ASSUME DS:CODE 
PUSH 
LDS 


DS 
SI, [PTRSAV] 


ASSUME DS:NOTHING 


LDS 


WERROR: POP 
ASSUME DS:CODE 
MOV 
WERROR2: MOV 
INT 
XOR 
PUSH 
JMP 


BADNDRV: 
POP 


MOV 
JMP 


SCAN4: 


SI,DWORD PTR [SI.COUNT] 


SCAN SWITCH 
AL,CL 

AL,AL 

SCAN4 

Ate Won 
SCAN4 


DS 


DX,OFFSET ERRMSG2 
AH ,9 

21H 

AX,AX 

AX 

SHORT ABORT 


DS 
DX,OFFSET ERRMSG1 
WE RROR2 


ASSUME DS:NOTHING 
;BX is number of floppies 


OR 


ASSUME DS:CODE 


ABORT: LDS 


BX,BX 
BADNDRV 
BX,4 
BADNDRV 
DS 


BX 
BX, [PTRSAV] 


ASSUME DS:NOTHING 


PUT SWITCH IN 


CAN SWITCH: 
XOR 


AX 
BYTE PTR [BX] .MEDIA,AL 
[DRVMAX] , AL 
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7DS:SI points to 
;CONFIG.SYS 


*-NoO units 


*USer error 


sUser error 


:;Save unit count 


Unit count 


WORD PTR [BX] .TRANS,OFFSET DRVSINIT ;SET 


[BX] . TRANS+2,CS 


;BREAK ADDRESS 


WORD PTR [BX] .COUNT,OFFSET INITAB 
;SET POINTER TO BPB ARRAY 


[BX] .COUNT+2,CS 
EXIT 


CL, VALUE IN BX 


BX,BX 
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GOT SWITCH: 


e 
, 
e 
’ 
° 
c 
e 
, 
e 
e 


CHKRET 


TERROR: 
NUMRET: 


ERRMSG1 
ERRMSG 2 
CODE 


CMP 
JNZ 
LODSB 
OR 
MOV 
LODSB 


ETNUM1:LODSB 


SUB 


CX,BX 


AL, 10 
NUMRET 
AL,"-" 
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GOT SWITCH 


AL,"/" 


SCAN SWITCH 


BYTE PTR {SI+1] ,"=* 


TERROR 


AL, 20H 
CL,AL 


WIPES OUT AX,DX ONLY 


AL,"0" 
CHKRET 
AL,9 

CHKRET 


AX, BX 
DX,10 
DX 
BX,AX 
GETNUM1 


CONVERT TO LOWER CASE 
GET SWITCH 
SKIP ":" 


=e we ZO 


GET NUMBER POINTED TO BY [SI] 


BX RETURNS NUMBER 


; GET RID OF RETURN ADDRESS 


"SMLDRV: Bad number of drives",13,10,"$" 


"SMLDRV: 


Invalid parameter",13,10,"$" 
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2.8.2 Character Device Driver 


The following program illustrates a character device driver 
program. 


geekkkkkk kkk KKK KKKKKKK A CHARACTER DEVICE ¥¥ KKK KKKKKKKKKKKKEK 


TITLE VT52 CONSOLE FOR 2.0 (IBM) 


eoeee#eeegeeereeeeesgeee#ee#rekeee#e##eeeefeeeeseee#5s5eeeg#trtsteee#eeeeerteteeee#eet ee e@ @ @ 


CR=13 ;CARRIAGE RETURN 

BACKS P=8 ; BACKSPACE 

ESC=1BH 

BRKADR=6CH ;006C BREAK VECTOR ADDRESS 

ASNMAX=200 ;SIZE OF KEY ASSIGNMENT BUFFER 
CODE SEGMENT BYTE 


ASSUME CS:CODE,DS:NOTHING,ES:NOTHING 


; C ON - CONSOLE DEVICE DRIVER 
CONDEV: ;HEADER FOR DEVICE "CON" 
DW ~Lyrk 
DW 1000000000010011B ;CON IN AND CON OUT 
DW STRATEGY 
DW ENTRY 
DB "CON 
; COMMAND JUMP TABLES 
CONTBL: 
DW CONSINIT 
DW EXIT 
DW EXIT 
DW CMDERR 
DW CONS READ 
DW CON$ RDND 
DW EXIT 
DW CONSFLSH 
DW CONSWRIT 
DW CONSWRIT 
DW EXIT 
DW EXIT 


CMDTABL DB "A' 
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SSELPLSLPLSLSLILELH LILES 


0 

an! 

> 
Huuuu wu ow 


STRATEGY: 
MOV 
MOV 
RET 


STRATP ENDP 


ENTRY: 
PUSH 
PUSH 
PUSH 
PUSH 


CUU ;Cursor up 
‘BR? 
CUD ;cursor down 
‘Cc! 
CUF ;cursor forward 
"Dp? 
CUB ;cursor back 
'H! 
CUH ;cursor position 
7" 
ED ;erase display 
"RK! 
EL ;erase line 
‘ys 
CUP ;Cursor position 
ee | 
PSCP ;Save cursor position 
Sk? 
PRCP ;restore cursor position 
t ' 
y. 
RM ;reset mode 
"y! 
SM sset mode 
00 


Device entry point 


0 ;LENGTH OF THIS COMMAND 

1 ;SUB UNIT SPECIFIER 

2 ; COMMAND CODE 

3 ;STATUS 

13 ;MEDIA DESCRIPTOR 

14 ; TRANSFER ADDRESS 

18 ;COUNT OF BLOCKS OR CHARACTERS 
20 ;FIRST BLOCK TO TRANSFER 

0 

FAR 


WORD PTR CS: [PTRSAV] ,BX 
WORD PTR CS: [PTRSAV+2] ,ES 
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PUSH DI 

PUSH BP 

PUSH DS 

PUSH ES 

PUSH BX 

LDS BX,CS: [PTRSAV] *;GET POINTER TO I/O PACKET 
MOV CX,WORD PTR DS: [BX] .COUNT ;CX = COUNT 
MOV AL,BYTE PTR DS: [BX] .CMD 

CBW 

MOV SI,OFFSET CONTBL 

ADD SI,AX 

ADD ST,AX 

CMP AL, 11 

JA CMDERR 

LES DI,DWORD PTR DS: [BX] . TRANS 

PUSH CS 

POP DS 


ASSUME DS:CODE 


IMP WORD PTR [SI] ;GO DO COMMAND 
PAGE 
;= SUBROUTINES SHARED BY MULTIPLE DEVICES 
a 
: EXIT - ALL ROUTINES RETURN THROUGH THIS PATH 
BUSSEXIT: sDEVICE BUSY EXIT 
MOV AH,00000011B 
JMP SHORT ERR1 
CMDERR: 
MOV AL,3 ;UNKNOWN COMMAND ERROR 
ERRSEXIT: 
MOV AH, 10000001B ;MARK ERROR RETURN 
JMP SHORT ERR] 
EXITP PROC FAR 
EXIT: MOV AH,00000001B 
ERR1: LDS BX,CS: [PTRSAV] 
MOV WORD PTR [BX].STATUS,AX ;MARK 


;OPERATION COMPLETE 
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BREAK KEY HANDLING 


MOV 
IRET 


WARNING - Variables are 
so be careful 


CS :ALTAH, 3 


Oo Fe 


ooooytwNnso 
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;RESTORE REGS AND RETURN 


; INDICATE BREAK KEY SET 


very order dependent, 
when adding new ones! 


; O = WRAP, 1 = NO WRAP 


;Special key handling 


cryire 


torom: 


LABEL 
DB 
DB 
dw 


cmp 
jnz 
MOv 
jmp 


cmp 
jz 

cmp 
jnz 
mov 


and 
mov 


CHROUT - WRITE OUT CHAR IN 


WORD 
00000111B 
0 

Ob800h 


al,13 

trylf 

[col] ,0 
short setit 


al,10 
LZ 

al,7 
tryback 


bx, [attrw] 
Bly? 
ah,14 


AL USING CURRENT ATTRIBUTE 


;CHARACTER ATTRIBUTE 
>BASE PAGE 
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int 
retS: ret 


tryback: 


outchr: 


outchrl: 


Lf: inc 


setit: mov 


Scroll: call 


jmp 
myscroll: 
MOv 


mov 


10h 


al,8 

outchr 
[col] ,@ 
ret5S 

[col] 

short setit 


bx, {attrw] 
cx,1 

ah,9 

10h 

[col] 

al, [col] 
al, {maxcol] 
setit 
[wrap] ,0 
outchrl 
[col] 


[col] ,0 
[row] 
[row] ,24 
setit 
[row] ,23 
scroll 


dh, row 
dl,col 
bh,bh 
ah,2 
10h 


getmod 
al,2 
myscroll 
al,3 
myscroll 
al,10 
torom 


bh, [attr] 
bi,” t 
bp, 80 
ax, [base] 
es,ax 
ds,ax 
di,di 
si,160 
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MOV cx,23*80 
cld 
cmp ax,0b800h 
jz colorcard 
rep movsw 
MOv ax,bx 
mov cx, bp 
rep stosw 
Sret: push cs 
pop ds 
ret 
colorcard: 
mov dx, 3dah 
wait2: in al,dx 
test al,8 
jz wait2 
mov al,25h 
Mov dx, 3d8h 
out dx,al sturn off video 
rep movsw 
Mov ax,bx 
mov cx,bp 
rep stosw 
mov al,29h 
mov dx, 3d8h 
out dx,al ;turn on video 
jmp sret 
GETMOD: MOV AH,15 
INT 16 sget column information 
MOV BPAGE, BH 
DEC AH 
MOV WORD PTR MODE,AX 
RET 


CONS READ: 

JCXZ CONSEXIT 
CONS LOOP: 

PUSH CX 

CALL CHRIN 

POP CX 

STOSB 

LOOP CON$ LOOP 
CONSEXIT: 

JMP EXIT 


CONSOLE READ ROUTINE 


;SAVE COUNT 
;GET CHAR IN AL 


;STORE CHAR AT ES:DI 


INPUT SINGLE CHAR INTO AL 


CHRIN: XOR AX,AX 
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XCHG 
OR 


INAGN: XOR 


ALT10: 


KEYRET: RET 


CONS RDND: 
MOV 


RDEXIT: LDS 

MOV 
EXVEC: JMP 
CONBUS: JMP 


CONSFLSH: 
MOV 


PUSH 
XOR 
MOV 
MOV 


; 
CONSWRIT: 


AL,ALTAH ;GET CHARACTER & ZERO ALTAH 
AL,AL 
KEYRET 


AH, AH 
22 


AX,AX ;Check for non-key after BREAK 
INAGN 

AL,AL ;SPECIAL CASE? 

KEYRET 

ALTAH , AH ;STORE SPECIAL KEY 


KEYBOARD NON DESTRUCTIVE READ, NO WAIT 


AL, [ALTAH] 
AL,AL 
RDEXIT 


CONS RDND 


BX, [PTRSAV] 
[BX] .MEDIA,AL 
EXIT 

BUSSEXIT 


KEYBOARD FLUSH ROUTINE 


{[ALTAH] ,0 ;Clear out holding buffer 

DS 

BP,BP 

DS , BP >Select segment 0 

DS:BYTE PTR 41AH,1EH ;Reset KB queue head 
;pointer 

DS:BYTE PTR 41CH,1EH *Reset tail pointer 

DS 

EXVEC 


CONSOLE WRITE ROUTINE 
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CONSLP: 


COUT : 


OUTC: 


S1B: 
S1A: 


JICXZ EXVEC 

PUSH CX 

MOV AH, 3 ;SET CURRENT CURSOR POSITION 
XOR BX,BX 

INT 16 

MOV WORD PTR [COL] ,DX 

POP cx 

MOV AL,ES: [DI] ;GET CHAR 
INC DI 

CALL OUTC ;OUTPUT CHAR 
LOOP CONSLP ;REPEAT UNTIL ALL THROUGH 
JMP EXVEC 

STI 

PUSH DS 

PUSH cs 

POP DS 

CALL OUTC 

POP DS 

IRET 

PUSH AX 

PUSH CX 

PUSH DX 

PUSH SI 

PUSH DI 

PUSH ES 

PUSH BP 

CALL VIDEO 

POP BP 

POP ES 

POP DI 

POP SI 

POP DX 

POP cx 

POP AX 

RET 


OUTPUT SINGLE CHAR IN AL TO VIDEO DEVICE 


MOV SI,OFFSET STATE 

JMP [ST] 

CMP AL,ESC ;ESCAPE SEQUENCE? 
JNZ S1B 

MOV WORD PTR [SI] ,OFFSET S2 

RET 

CALL CHROUT 

MOV WORD PTR [STATE] ,OFFSET Sl 


RET 
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S2: PUSH AX 
CALL GETMOD 
POP AX 
MOV BX,OFFSET CMDTABL-3 
S7A: ADD BX,3 
CMP BYTE PTR [BX] ,0 
JZ S1A 
CMP BYTE PTR [BX] ,AL 
JNZ S7A 
JMP WORD PTR [BX+1] 
MOVCUR: CMP BYTE PTR [BX] ,AH 
JZ SETCUR 
ADD BYTE PTR [BX] ,AL 
SETCUR: MOV DX,WORD PTR COL 
XOR BX,BX 
MOV AH, 2 
INT 16 
JMP S1A 
CUP: MOV WORD PTR [SI] ,OFFSET CUP1 
RET 
CUPI1: SUB AL, 32 
MOV BYTE PTR [ROW] ,AL 
MOV WORD PTR [SI] ,OFFSET CUP2 
RET 
CUPZ; SUB AL, 32 
MOV BYTE PTR [COL] ,AL 
JMP SETCUR 
SM: MOV WORD PTR [SI] ,OFFSET SIA 
RET 
CUH: MOV WORD PTR COL,0O 
JMP SETCUR 
CUF : MOV AH ,MAXCOL 
MOV AL, 1 
CUF 1: MOV BX,OFFSET COL 
JMP MOVCUR 
CUB: MOV AX, 0OOFFH 
JMP CUF1 
CUU : MOV AX, 00FFH 
CUoUL1s MOV BX,OFFSET ROW 
JMP MOVCUR 
CUD: MOV AX, 23*256+1 


JMP CUU1 
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PSCP : MOV 


PRCP: MOV 


ED: CMP 


CONS INIT: 
int 
and 
cmp 
jnz 
MOV 

iscolor: 


AX,WORD PTR COL 
SAVCR,AX 
SETCUR 


AX,SAVCR 
WORD PTR COL,AX 
SETCUR 


BYTE PTR [ROW] ,24 
ELL 


CX,WORD PTR COL 
DH, 24 
ERASE 


BYTE PTR [COL] ,0 
CX,WORD PTR [COL] 
DH , CH 

DL ,MAXCOL 
BH,ATTR 

AX ,0600H 

16 

SETCUR 


WORD PTR [SI],OFFSET RM1 


CX ,CX 
CH, 24 
EL2 


Lin 
al,00110000b 
al,00110000b 
iscolor 
[base] ,0b000h slook for bw card 
al,00010000b 
setbrk 
[mode] ,0 
[maxcol] ,39 


BX,BX 

DS , BX 

BX,BRKADR 

WORD PTR [BX] ,OFFSET BREAK 
WORD PTR [BX+2],CS 


BX, 29H*4 
WORD PTR [BX] ,OFFSET COUT 
WORD PTR [BX+2],CS 
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;look for 40 col mode 
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LDS BX,CS: [PTRSAV] 
MOV WORD PTR [BX] .TRANS,OFFSET CONSINIT 
;SET BREAK ADDRESS 
MOV [BX] . TRANS+2,CS 
JMP EXIT 
CODE ENDS 


END 
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CHAPTER 3 


MS-DOS TECHNICAL INFORMATION 


3.1 MS-DOS INITIALIZATION 


MS-DOS initialization consists of several steps. Typically, 
a ROM (Read Only Memory) bootstrap obtains control, and then 
reads the boot sector off the disk. The boot sector’ then 
reads the following files: 


I0.SYS 
MSDOS .SYS 


Once these files are read, the boot process begins. 


3.2 THE COMMAND PROCESSOR 


The command processor supplied with MS-DOS (file 
COMMAND.COM.) consists of 3 parts: 


l. A resident part resides in memory immediately 
following MSDOS.SYS and its data area. This part 
contains routines’ to process Interrupts 23H 
(CONTROL-C Exit Address) and 24H (Fatal Error Abort 
Address), aS well as a routine to reload _ the 
transient part, if needed. All standard MS-DOS 
error handling is done within this part of 
COMMAND .COM. This includes displaying error 
messages and processing the Abort, Retry, or Ignore 
messages. 





2. An initialization part follows the resident part. 
During startup, the initialization part is given 
control; it contains the AUTOEXEC file processor 
Setup routine. The initialization part determines 
the segment address at which programs can _ be 
loaded. It is overlaid by the first program 


COMMAND.COM loads because it is no longer needed. 
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3. A transient part is loaded at the high end of 
memory. This part contains all of the internal 
command processors and the batch file processor. 








The transient part of the command processor 


produces the system prompt (Such as A>), reads the 
command from keyboard (or batch file), and causes 
it to be executed. For external commands, this 
part builds a command line and issues the EXEC 


system call (Function Request 4BH) to load and 
transfer control to the program, 


3.3 MS-DOS DISK ALLOCATION 
The MS-DOS area is formatted as follows: 
Reserved area - variable size 


First copy of file allocation 
table - variable size 


Second copy of file allocation 
table - variable size 
(optional) 

Additional copies of file 
allocation table - variable 
Size (optional) 

Root directory - variable size 


File data area 
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Allocation of space for a file in the data area is not 


pre-allocated. The space is allocated one cluster at a 
time. A cluster consists of one or more consecutive 
sectors; all of the clusters for a file are "chained" 


together in the File Allocation Table (FAT). (Refer to 
Section 3.5, "File Allocation Table," for more information 
on the FAT.) There is uSually a second copy of the FAT kept, 
for consistency. Should the disk develop a bad sector in 
the middle of the first FAT, the second can be uSed. This 
avoids loss of data due to an unuSable disk. 


3.4 MS-DOS DISK DIRECTORY 


FORMAT builds the root directory for all disks. Its 
location on disk and the maximum number of entries are 
dependent on the media. 


Since directories other than the root directory are regarded 
as files by MS-DOS, there is no limit to the number of files 
they may contain. 
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All directory entries are 32 bytes in length, and are in 


following format (note that byte offsets are 
hexadecimal): 
0-7 Filename. Eight characters, left aligned and 


padded, if necessary, with blanks. The first 
byte of this field indicates the file status 
as follows: 


OOH The directory entry has never been 
used. This is used to limit the 
length of directory searches, for 
performance reasons. 


2EH The entry is for a directory. If 
the second byte is also 2EH, 
then the cluster field contains 
the cluster number of this 
directory's parent directory 
(OOOOH if the parent directory 
is the root directory). Other- 
wise, bytes 01H through OAH 
are all spaces, and the cluster 
field contains the cluster 
number of this directory. 


E5H The file was used, but it has been 
erased. 


Any other character is the first character 
of a filename. 


8-0OA Filename extension. 


OB File attribute. The attribute byte is 
mapped as follows (values are in hexa- 
decimal): 


01 File is marked read-only. An attempt 
to open the file for writing using 
the Open File system call (Function 
Request 3DH) results in an error 
code being returned. This value 
can be used along with other 
values below. Attempts to delete 
the file with the Delete File 
system call (13H) or Delete a 
Directory Entry (41H) will also 
fail. 


02 Hidden file. The file is excluded 
from normal directory searches. 


3-4 


the 
in 
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04 System file. The file is excluded 
from normal directory searches. 


08 The entry contains the volume label 
in the first 11 bytes. The entry 
contains no other uSable information 
(except date and time of creation), 
and may exist only in the root 
directory. 


10 The entry defines a sub-directory, 
and is excluded from normal 
directory searches. 


20 Archive bit. The bit is set to “on" 
whenever the file has been written 
to and closed. 


Note: The system files (IO.SYS and 
MSDOS.SYS) are marked as read-only, 
hidden, and system files. Files can 

be marked hidden when they are created. 
Also, the read-only, hidden, system, 
ang archive attributes may be changed 
through the Change Attributes system 
call (Function Request 43H). 


0C=-15 Reserved. 
16-17 Time the file was created or last updated. 
The hour, minutes, and seconds are mapped 


into two bytes as follows: 


Offset 17H 
|}H|H|H|[ HI] HI[M[M [MI 
7 3 2 


Offset 16H 
IMI M[M[ S/S i s|[ ss 
5 4 0 
where: 
H is the binary number of hours (0-23) 
M is the binary number of minutes 
(0-59) 
S is the binary number of two-second 


increments 


MS-DOS TECHNICAL INFORMATION Page 3-6 


18-19 Date the file was created or last updated. 


The year, month, and day are mapped into two bytes 
as follows: 


Offset 19H 
RZ SES ee ee ee ae eS 
f 1 0 
Offset 18H 
|mM|mM[{[M]/D]D|][D]D]D | 
5 4 0 
where: 


Y is 0-119 (1980-2099) 
M is 1-12 
D is 1-31 


1A-1B Starting cluster; the cluster number 
of the first cluster in the file. 


Note that the first cluster for data space 
on all disks is cluster 002. 


The cluster number is stored with the 
least significant byte first. 


NOTE 


Refer to the Section 3.5.1, 
"How to Use the File 
Allocation Table," for details 
about converting cluster 
numbers to logical sector 
numbers. 


1C-1F File size in bytes. The first word of this 
four-byte field is the low-order part of 
the size. 
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3.5 FILE ALLOCATION TABLE (FAT) 


The following information is included for system programmers 
who wish to write installable device drivers. This section 
explains how MS-DOS uses the File Allocation Table _ to 
convert the clusters of a file to logical sector numbers. 
The driver is then responsible for locating the _ logical 


sector on disk. Programs must use the MS-DOS file 
Management function calls for accessing files; programs 
that access the FAT are not guaranteed to be 


upwardly-compatible with future releases of MS-DOS. 


The File Allocation Table is an array of 12-bit entries (1.5 
bytes) for each cluster on the disk. The first two FAT 
entries map a portion of the directory; these FAT entries 
indicate the size and format of the disk. 


The second and third bytes currently always contain FFH. 


The third FAT entry, which starts at byte offset 4, begins 
the mapping of the data area (cluster 002). Files in the 
data area are not always written sequentially on the disk. 
The data area is allocated one cluster at a time, skipping 


over clusters already allocated. The first free cluster 
found will be the next cluster allocated, regardless of its 
physical location on the _ disk. This permits the most 


efficient utilization of disk space because clusters made 
available by erasing files can be allocated for new files. 


Each FAT entry contains three hexadecimal characters: 
000 If the cluster is unused and available. 


FF7 The cluster has a bad sector in it. 
MS-DOS will not allocate such a cluster. 
CHKDSK counts the number of bad clusters 
for its report. These bad clusters are 
not part of any allocation chain. 


FF8-FFF Indicates the last cluster of a file. 


XXX Any other characters that are 
the cluster number of the next cluster in 
the file. The cluster number of the first 
cluster in the file is kept in the file's 
directory entry. 


The File Allocation Table always begins on the first section 
after the reserved sectors. If the FAT is larger than one 
sector, the sectors are continguous. Two copies of the FAT 
are usually written for data integrity. The FAT is read 
into one of the MS-DOS buffers whenever needed (open, read, 
write, etc.). For performance reasons, this buffer is given 
a high priority to keep it in memory as long as possible. 
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3.5.1 How To Use The File Allocation Table 


Use the directory entry to find the starting cluster of the 


file. 


Next, to locate each subsequent cluster of the file: 


Multiply the cluster number just used by 1.5 (each 
FAT entry is 1.5 bytes long). 


The whole part of the product is an offset into the 
FAT, pointing to the entry that maps the cluster 


just used. That entry contains the cluster number 
of the next cluster of the file. 


Use a MOV instruction to move the word at the 
calculated FAT offset into a register. 


If the last cluster used was an even number, keep 
the low-order 12 bits of the register by ANDing it 
with FFF; otherwise, keep the high-order 12 bits 
by shifting the register right 4 bits with a SHR 
instruction. 


If the resultant 12 bits are FF8H-FFFH, the _ file 
contains no more clusters. Otherwise, the 12 bits 
contain the cluster number of the next cluster in 
the file. 


To convert the cluster to a logical sector number (relative 


sector, 
DEBUG) : 


Such as that used by Interrupts 25H and 26H and by 


Subtract 2 from the cluster number. 


Multiply the result by the number of sectors’ per 
cluster. 


Add to this result the logical sector number of the 
beginning of the data area. 
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3.6 MS-DOS STANDARD DISK FORMATS 


On an MS-DOS disk, the clusterS are arranged on disk to 
minimize head movement for multi-sided media. All of the 
space on a track (or cylinder) is allocated before moving on 
to the next’ track. This is accomplished by using the 
sequential sectors on the lowest-numbered head, then all the 
sectors on the next head, and so on, until all sectors on 
all heads of the track are used. The next sector to be used 
will be sector 1 on head 0 of the next track. 


For disks, the following can be used: 


Sectors/ FAT size Dir Dir Sectors/ 
Track Sectors Sectors Entries Cluster 





Figure 3.1 5-1/4" Disk Format 


The first byte of the FAT can sometimes be used to determine 
the format of the disk. The following 5-1/4" formats have 
been defined for the IBM Personal Computer, based on values 
of the first byte of the FAT. The formats in Table 3.1 are 
considered to be the standard disk formats for MS-DOS. 


MS-DOS TECHNICAL INFORMATION Page 3-10 


Table 3.1 MS-DOS Standard Disk Formats 


5-1/4 5-1/4 5-1/4 5-1/4 8 8 8 

No. sides i. i. 2 2 l l zZ 
Tracks/side 40 40 40 40 77 77 77 
Bytes/ 

sector 512 512 512 512 128 128 1024 
Sectors/ 

track 8 9 8 9 26 26 8 
Sectors/allo- 

cation unit i l 2 2 4 4 Ll 
Reserved 

sectors 1 l 1 t l 4 nf 
No. FATS 2 2 2 2 2 2 2 
Root directory 

entries 64 64 112 112 68 68 192 
No. sectors 320 360 640 Tau 2002 2002 616 


Media Descriptor 
Byte FE FC FF FD FE* FD FE* 


Sectors for 
1 FAT i, 2 1 2 6 6 Z 


*The two media descriptor bytes that are the same for 
8" disks (FEH) is not a misprint. To establish 
whether a disk is Single- or double-density, a 
read of a single-density address mark should be 
made. If an error occurs, the media is double- 
density. 
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CHAPTER 4 


MS-DOS CONTROL BLOCKS AND WORK AREAS 


4.1 TYPICAL MS-DOS MEMORY MAP 


0000:0000 Interrupt vector table 
XXXX: 0000 IO0.SYS - MS-DOS interface to hardware 
XXXX:0000 MSDOS.SYS - MS-DOS interrupt handlers, 


service routines (Interrupt 21H functions) 


MS-DOS buffers, control areas, and installed 
device drivers 


XXXX: 0000 Resident part of COMMAND.COM - Interrupt 
handlers for Interrupts 22H (Terminate 
Address), 23H (CONTROL-C Exit Address), 
24H (Fatal Error Abort Address) 
and code to reload the transient part 


XXXX:0000 External command or utility - (.COM or 
-EXE file) 

XXXX: 0000 User stack for .COM files (256 bytes) 

XXXX:0000 Transient part of COMMAND.COM - Command 
interpreter, internal commands, batch 
processor 


l. Memory map addresses are in segment:offset format. 
For example, 0090:0000 is absolute address 0900H. 


2. User memory is allocated from tthe lowest end of 
available memory that will meet the allocation 
request. 
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4.2 MS-DOS PROGRAM SEGMENT 


When an external command is typed, or when you execute a 
program through the EXEC system call, MS-DOS determines the 
lowest available free memory address to use as the start of 
the program. This area is called the Program Segment. 


The first 256 bytes of the Program Segment are set up by the 
EXEC system call for the program being loaded into memory. 
The program is then loaded following this’ block. An .EXE 
file with minalloc and maxalloc both set to zero is loaded 
as high as possible. 


At offset 0 within the Program Segment, MS-DOS builds’ the 


Program Segment Prefix control block. The program returns 
from EXEC by one of four methods: 


1. A long jump to offset 0 in the Program Segment 
Prefix 


2. By issuing an INT 20H with CS:0 pointing at the PSP 


3. By issuing an INT 21H with register AH=0 with CS:0 
pointing at the PSP, or 4CH and no restrictions on 
cs 


4. By along call to location 50H in the Program 
Segment Prefix with AH=0 or Function Request 4CH 


NOTE 


It is the responsibility of 
all programs to ensure that 
the CS register contains’ the 
segment address of the Program 


Segment Prefix when 
terminating via any of these 
methods, except Function 


Request 4CH. For this reason, 
uSing Function Request 4CH is 
the preferred method. 


All four methods result in transferring control to. the 
program that issued the EXEC. During this’ returning 
process, Interrupts 22H, 23H, and 24H (Terminate Address, 
CONTROL-C Exit Address, and Fatal Error Abort Address) 
addresses are restored from the values saved in the Program 
Segment Prefix of the terminating program. Control is then 
given to the terminate address. If this iS a= program 
returning to COMMAND.COM, control transfers to its resident 
portion. If a batch file was in process, it is continued; 
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otherwise, COMMAND.COM performs a checksum on the transient 
part, reloads it if necessary, then issues the system prompt 
and waits for you to type the next command. 


When a program receives control, the following conditions 
are in effect: 


For all programs: 


The segment address of the passed environment is 
contained at offset 2CH in the Program Segment 
Prefix. 


The environment is ae_eseries of ASCII strings 
(totaling less than 32K) in the form: 


NAME=parameter 


Each string is terminated by a byte of zeros, and 
the set of strings is terminated by another byte of 
zeros. The environment built by the command 
processor contains at least a COMSPEC= string (the 
parameters on COMSPEC define the path used _ by 
MS-DOS to locate COMMAND.COM on disk). The last 
PATH and PROMPT commands issued will also be in the 
environment, along with any environment strings 
defined with the MS-DOS SET command. 


The environment that is passed is a copy of the 
invoking process environment. If your application 
uses a "keep process" concept, you should be aware 
that the copy of the environment passed to you is 
static. That is, it will not change even if 
subsequent SET, PATH, Or PROMPT commands are 
issued. 


Offset 50H in the Program Segment Prefix contains 
code to call the MS-DOS function dispatcher. By 
placing the desired function request number in AH, 
a program can issue a far call to offset 50H to 
invoke an MS-DOS function, rather than issuing an 
Interrupt 21H. Since this is a call and not an 
interrupt, MS-DOS may place any code appropriate to 
making a system call at this position. This makes 
the process of calling the system portable. 





The Disk Transfer Address (DTA) is set to 80H 
(default DTA in the Program Segment Prefix). 
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File control blocks at 5CH and 6CH are _ formatted 
from the first two parameters typed when the 
command was entered. If either parameter contained 
a pathname, then the corresponding FCB contains 
only the valid drive number. The filename field 
will not be valid. 


An unformatted parameter area at 81H contains all 
the characters typed after the command (including 
leading and imbedded delimiters), with the byte at 
80H set to the number of characters. If the <, >, 
Or parameters were typed on the command line, they 
(and the filenames associated with them) will not 
appear in this area; redirection of standard input 
and output is transparent to applications. 


Offset 6 (One word) contains the number of bytes 
available in the segment. 


Register AX indicates whether or not the drive 
specifiers (entered with the first two parameters) 
are valid, as follows: 


AL=FF if the first parameter contained an 
invalid drive specifier (otherwise AL=00) 


AH=FF if the second parameter contained an 
invalid drive specifier (otherwise AH=00) 


Offset 2 (one word) contains the Segment address of 
the first byte of unavailable memory. Programs 
must not modify addresses beyond this point unless 
they were obtained by allocating memory via the 
Allocate Memory system call (Function Request 48H). 
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FOr 


FOr 


Executable (.EXE) programs: 


DS and ES registers are set to point to the Program 
Segment Prefix. 


CS,IP,SS, and SP registers are set to the values 
passed by MS-LINK. 


Executable (.COM) programs: 


All four segment registers contain the segment 
address of the initial allocation block that starts 
with the Program Segment Prefix control block. 


All of user memory is allocated to the program. If 
the program invokes another program’ through 
Function Request 4BH, it must first free some 
memory through the Set Block (4AH) function call, 
to provide space for the program being executed. 


The Instruction Pointer (IP) is set to 100H. 


The Stack Pointer register is set to the end of the 
program's segment. The segment size at offset 6 is 
reduced by 100H to allow for a stack of that size. 


A word of zeros is placed on top of the stack. 
This is to allow a user program to exit to 
COMMAND.COM by doing a RET inStruction last. This 
assumes, however, that the uSer has maintained his 
stack and code segments. 
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Figure 4.1 illustrates the format of the Program Segment 
Prefix. All offsets are in hexadecimal. 


(offsets in hex) 


Long call to MS-DOS 
INT 20H Reserved function dispatuher 
(5 bytes) 


Terminate address CTRL-C exit 
(IP, CS) address (IP) 


CTRL-C exit Hard error exit address 
address (CS) (IP, CS) 


Formatted Parameter Area 1 formatted as standard 
unopened FCB 6CH 


Formatted Parameter Area 2 formatted as standard 
unopened FCB (overlaid if FCB at 5CH is opened) 


Unformatted Parameter Area 
(default Disk Transfer Area) 





100 


Figure 4.1 Program Segment Prefix 


IMPORTANT 


Programs must not alter. any 
part of the Program Segment 
Prefix below offset 5CH. 
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CHAPTER 5 


-EXE FILE STRUCTURE AND LOADING 


NOTE 


This chapter describes .EXE 
file Structure and _ loading 
procedures for systems’ that 
use a version of MS-DOS that 
is lower than 2.0. For MS-DOS 
2.0 and higher, use Function 
Request 4BH, Load and Execute 
a Program, to load (or load 
and execute) an .EXE file. 


The .EXE files produced by MS-LINK consist of two parts: 
Control and relocation information 
The load module 
The control and relocation information is at the beginning 
of the file in an area called the header. The load module 
immediately follows the header. 


The header is formatted as follows. (Note that offsets are 
in hexadecimal.) 


Offset Contents 

00-01 Must contain 4DH, SAH. 

02-03 Number of bytes contained in last page; 
this is useful in reading overlays. 

04-05 Size of the file in 512-byte pages, 
including the header. 

06-07 Number of relocation entries in table. 

08-09 Size of the header in 16-byte paragraphs. 


This is used to locate the beginning of 
the load module in the file. 
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OA-OB Minimum number of 16-byte paragraphs 
required above the end of the loaded 
program. 


0C-0D Maximum number of 16-byte paragraphs 
required above the end of the loaded 
program. If both minalloc and max- 
alloc are 0, then the program will 
be loaded as high as possible. 


OE-OF Initial value to be loaded into stack 
segment before starting program exe- 
cution. This must be adjusted by 
relocation. 


LO=1L1 Value to be loaded into the SP register 
before starting program execution. 

12-13 Negative sum of all the words in the 
file. 

14-15 Initial value to be loaded into the IP 
register before starting program 
execution. 

16-17 Initial value to be loaded into the CS 


register before starting program 
execution. This must be adjusted by 
relocation. 


18=19 Relative byte offset from beginning of 
run file to relocation table. 

1A-1B The number of the overlay as generated by 
MS-LINK. 


The relocation table follows the formatted area described 
above. This table consists of a variable number of 
relocation items. Each relocation item contains two fields: 
a two-byte offset value, followed by a two-byte segment 
value. These two fields contain the offset into the load 
module of a word which requires modification before the 
module is given control. The following steps describe this 
process: 


1. The formatted part of the header is read _ into 
memory. Its size is 1BH. 


2. A portion of memory is allocated depending on _ the 
size of the load module and the allocation numbers 
(OA-OB and OC-OD). MS-DOS attempts to allocate 
FFFFH paragraphs. This will always fail, returning 
the size of the largest free block. If this’ block 
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is smaller than minalloc and loadsize, then there 


will be no memory error. If this block is’ larger 
than maxalloc and loadsize, MS-DOS will allocate 
(maxalloc + loadsize). Otherwise, MS-DOS will 


allocate the largest free block of memory. 


A Program Segment Prefix is built in the lowest 
part of the allocated memory. 


The load module size is calculated by subtracting 
the header size from the file size. Offsets 04-05 
and 08-09 can be used for this calculation. The 
actual size is downward-adjusted based on_ the 
contents of offsets 02-03. Based on the setting of 
the high/low loader switch, an appropriate segment 
is determined at which to load the load module. 
This segment is called the start segment. 


The load module is read into memory beginning with 
the start segment. 


The relocation table items are read into a work 
area. 


Each relocation table item segment value is added 
to the start segment value. This calculated 
segment, plus the relocation item offset value, 
points to a word in the load module to which is 
added the start segment value. The result is 
placed back into the word in the load module. 


Once all relocation items have been processed, the 
SS and SP registers are set from the values in the 
header. Then, the start Segment value is added to 
SS. The ES and DS registers are set to the segment 
address of the Program Segment Prefix. The start 
segment value is added to the header CS register 
value. The result, along with the header IP value, 
is the initial CS:IP to transfer to before starting 
execution of the program. 
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CHAPTER 6 


INTEL RELOCATABLE OBJECT MODULE FORMATS 


6.1 INTRODUCTION 


This chapter presents the object record formats that define 
the object language for the 8086 microprocessor. The 8086 
object language is the output of all language translators 
that have the 8086 as the target processor. The 8086 object 
language is input and output for object language processors 
such as linkers and librarians. 


The 8086 object module formats permit you to specify 
relocatable memory images that may be linked together. 
Capabilities are provided that allow efficient use of the 
memory mapping facilities of the 8086 microprocessor. 


The following table lists the record formats that are 
supported by Microsoft. These record formats are described 
in this chapter. Record formats that are preceded by an 
asterisk (*) deviate from the Intel specification. 


INTEL RELOCATABLE OBJECT MODULE FORMATS Page 6-2 


Table 6.1 Object Module Record Formats 


T-MODULE HEADER RECORD 
LIST OF NAMES RECORD 
*SEGMENT DEFINITION RECORD 
*GROUP DEFINITION RECORD 
*TYPE DEFINITION RECORD 


Symbol Definition Records 
*PUBLIC NAMES DEFINITION RECORD 
*EXTERNAL NAMES DEFINITION RECORD 
*LINE NUMBERS RECORD 


Data Records 
LOGICAL ENUMERATED DATA RECORD 
LOGICAL ITERATED DATA RECORD 


FIXUP RECORD 


*MODULE END RECORD 
COMMENT RECORD 


6.2 DEFINITION OF TERMS 
The following terms are fundamental to the 8086 relocation 
and linkage. 


OMF - Object Module Formats. 


MAS - Memory Address Space. The 8086 MAS is 1 megabyte 
(1,048,576). Note that the MAS is distinguished from actual 
memory, which may occupy only a portion of the MAS. 


MODULE - an "inseparable" collection of object code = and 
other information produced by a translator. 


T-MODULE - A module created by a translator, such as Pascal 
or FORTRAN. 
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The following restrictions apply to object modules: 


1. Every module should have a name. Translators will 
provide names for T-modules, providing a default 
name (possibly the filename or a null name) iif 
neither source code nor user specifies otherwise. 


2. Every T-module in a collection of linked modules 
must have a different name, so that symbolic 
debugging systems can distinguish the various’7 line 
numbers and local symbols. This restriction is not 
required by the Linker, and is not enforced by it. 


FRAME - A contiguous region of 64K of MAS, beginning on a 
paragraph boundary (i.e., on a multiple of 16 bytes). This 
concept is useful because the content of the four 8086 
segment registers defines four (possibly overlapping) 
FRAMES; no 16-bit address in the 8086 code can access a 
memory location outside of the current four FRAMEs. 


LSEG - Logical Segment - A contiguous region of memory whose 
contents are determined at translation time (except for 
address-binding). Neither size nor location in MAS are 
necessarily determined at translation time: size, although 
partially fixed, may not be final because the LSEG may _ be 
combined at LINK time with other LSEGs, forming a single 
LSEG. An LSEG must not be larger than 64K, so that it can 
fit in a FRAME. This means that any byte in an LSEG may be 
addressed by a 16-bit offset from the base of a FRAME 
covering the LSEG. 


PSEG - Physical Segment - This term iS equivalent to FRAME. 
Some people prefer "PSEG" to "FRAME" because the terms 
"PSEG" and "LSEG" reflect the "physical" and "logical" 
nature of the underlying segments. 


FRAME NUMBER - Every FRAME beginS On a paragraph boundary. 
The "paragraphs" in MAS can be - numbered from 0 through 
65535. These numbers, each of which defines a FRAME, are 
called FRAME NUMBERS. 
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PARAGRAPH NUMBER - This term iS equivalent to "FRAME 
NUMBER." 


PSEG NUMBER - This term iS equivalent to "FRAME NUMBER." 


GROUP - A collection of LSEGsS defined at translation time, 
whose final locations in MAS have been constrained such that 
there will be at least one FRAME which covers (contains) 
every LSEG in the collection. 


The notation "Gr A(X,Y,Z,)" means that LSEGsS X, Y and Z form 
a group whose name is A. The fact that X, Y and Z are all 
LSEGs in the same group does not imply any ordering of X, Y 
and 2zZ in MAS, nor does it imply any contiguity between X, Y 


— —— ——— ———_ —_ —_- — —_—— ———_—_—— a oo ——————$$— —$—— —_-_ _— 
—_——— 


The Microsoft Linker does not currently allow an LSEG to _ be 
a member of more than one group. The Linker will ignore all 
attempts to place an LSEG in more than one group. 


CANONIC - Any location in MAS is contained in exactly 4096 
distinct FRAMES; but one of these FRAMES can _ be 
distinguished because it has a higher FRAME NUMBER. This 
distinguished FRAME is called the canonic FRAME of the 
location. In other words, the canonic frame of a given byte 
is the frame so chosen that the byte's offset from that 
frame lies in the range 0 to 15 (decimal). Thus, if FOO is 
a symbol defining a memory location, one may speak of the 
"Canonic FRAME of FOO", or of "FOO'S canonic FRAME". By 
extension, if S 1S any set of memory locations, then there 
existS a unique FRAME which has the lowest FRAME NUMBER in 
the set of canonic FRAMES of the locations in S. This 
unique FRAME is called the canonic FRAME of the set SG. 
Thus, we may speak of the canonic FRAME of an LSEG or of a 
group of LSEGs. 
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SEGMENT NAME —- LSEGS are assigned segment names at 
translation time. These names serve two purposes: 


1. They play a role at LINK time in determining which 
LSEGS are combined with other LSEGs. 


2. They are used in assembly source code to specify 
groups. 


CLASS NAME - LSEGs may optionally be assigned Class Names at 
translation time. Classes define a partition on LSEGS: two 
LSEGsS are in the same class if they have the same Class 
Name. 


The Microsoft Linker applies the following semantics’ to 
class names. The class name "CODE" or any class name whose 
suffix is "CODE" implies that all segments of said class 
contain only code and may be considered read-only. Such 
segments may be overlayed if the user specifies the module 
containing the segment as part of an overlay. 


OVERLAY NAME - LSEGS may optionally be assigned an _ overlay 
name. The overlay name of an LSEG is ignored by MS-LINK 
(version 2.40 and later versions), but it is used by Intel 
relocation and Linkage products. 


COMPLETE NAME - The complete name of an LSEG consists of the 
Segment Name, Class Name, and Overlay Name. LSEGs from 
different modules will be combined if their Complete Names 
are identical. 
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6.3 MODULE IDENTIFICATION AND ATTRIBUTES 


A module header record is always the first record in a 
module. It provides a module name. 


In addition to a name, a module may have the attribute of 
being a main program as well as having a specified starting 
address. When linking multiple modules together, only one 
module with the main attribute should be given. 


In summary, modules may or may not be main and may or _ may 
not have a Starting address. 


6.4 SEGMENT DEFINITION 


A module is a collection of object code defined by a 
sequence of records produced by a translator. The object 
code represents contiguous regions of memory whose contents 
are determined at translation time. These regions are 
Called LOGICAL SEGMENTS (LSEGS). A module defines’ the 
attributes of each LSEG. The SEGMENT DEFINITION RECORD 
(SEGDEF) is the vehicle by which all LSEG information (name, 


length, memory alignment, etc.) iS maintained. The LSEG 
information iS required when multiple LSEGS are combined and 
when segment addressability (See Section 6.5, "Segment 


Addressing") is established. The SEGDEF records are 
required to follow the first header record. 


6.5 SEGMENT ADDRESSING 


The 8086 addressing mechanism provides segment base 
registers from which a 64K-byte region of memory, called a 
FRAME, may be addressed. There iS one code segment’ base 
register (CS), two data segment base registers (DS, ES), and 
one stack segment base register (SS). 


The possible number of LSEGs that may make up a memory image 
far exceeds the number of available base registers. fThus, 
base registers may require frequent loading. This would be 
the case in a modular program with many small data and/or 
code LSEGs. 


Since such frequent loading of base registers is 
undesirable, it iS a good Strategy to collect many small 
LSEGs together into a single unit that will fit in one 
memory frame so that all the LSEGs may be addressed using 
the same base register value. This addressable unit is a 
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GROUP and has been defined earlier in the DEFINITION OF 
TERMS. 


To allow addressability of objects within a GROUP to _ be 
established, each GROUP must be explicitly defined in the 
module. The GROUP DEFINITION RECORD (GRPDEF) provides a 
list of constituent segments either by segment name or by 
segment attribute such as "the segment defining symbol FOO" 
or "the segments with class name ROM." 


The GRPDEF records within a modul2 must follow all SEGDEF 
records aS GRPDEF records may reference SEGDEF records in 
defining a GROUP. The GRPDEF records must also precede all 
other records except header records, as the Linker must 
process them first. 


6.6 SYMBOL DEFINITION 


MS-LINK Supports three different types of records that fall 
into the class of symbol definition records. The two most 
important types are PUBLIC NAMES DEFINITION RECORDS 
(PUBDEFs) and EXTERNAL NAMES DEFINITION RECORDS (EXTDEFsS). 
These types are used to define globally visible procedures 


and data items and to resolve external references. In 
addition, TYPDEF records are used by MS-LINK for’ the 
allocation of communal variables (see Section 6.15 


"Microsoft Type Representations for Communal Variables".) 


6.7 INDICES 


"Index" fields occur throughout this document. An index is 
an integer that selects some particular item from a 
collection of such items. (List of examples: NAME INDEX, 
SEGMENT INDEX, GROUP INDEX, EXTERNAL INDEX, TYPE JNDEX.) 


NOTE 
An index is normally a 
positive number. The index 


value zero is reserved, = and 
May carry a special meaning 
dependent upon the type of 
index (e.g., a Segment Index 


of zero specifies the 
"Unnamed," absolute 
pseudo-segment; a Type Index 


of zero specifies the "Untyped 
type", which is different from 
"Decline to state"). 
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In general, indices must assume values quite large (that is, 
much larger than 255). Nevertheless, a great number of 
object files will contain no indices with values’ greater 
than 50 or 100. Therefore, indices will be encoded in 1 or 
2 bytes, as required. 


The high-order (left-most) bit of the first (and possibly 
the only) byte determines whether the index occupies one 
byte or two. If the bit is 0, then the index is a _ number 
between 0 and 127, occupying one byte. If the bit is l, 
then the index is a number between 0 and 32K-1, occupying 
two bytes, and is determined as follows: the low-order 8 
bits are in the second byte, and the high-order 7 bitS are 
in the first byte. 


6.8 CONCEPTUAL FRAMEWORK FOR FIXUPS 


A "fixup" is some modification to object code, requested by 
a translator, performed by the Linker, achieving address 
binding. 


NOTE 
This definition of “fixup” 
accurately represents the 
viewpoint maintained by the 
Linker. Nevertheless, the 


Linker can be used to achieve 
modifications of object code 
(i.@ey “Elxups") that do not 
conform to this definition. 
For example, the binding of 
code to either hardware 
floating point or software 
floating point Subroutines is 
a modification to an operation 
code, where the operation code 
is treated as if it were an 


address. The previous 
definition of "fixup™ is not 
intended to disallow Or 
disparage object code 


modifications. 
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8086 translators specify a fixup by giving four data: 


1. The place and type of a LOCATION to be fixed up 


2. One of two possible fixup MODEs 


3. A TARGET, which iS a memory address to which 
LOCATION must refer 


4. A FRAME defining a context within which the 
reference takes place 


LOCATION - There are 5 types of LOCATION: a POINTER, a 
BASE, an OFFSET, a HIBYTE, and a LOBYTE. 


The vertical alignment of the following figure illustrates 
four points. (Remember that the high-order byte of a word 
in 8086 memory is the byte with the higher address.) 


1. A BASE is the high-order word of a pointer (and the 
Linker doesn't care if the low-order word of the 
pointer is present or not). 


2. An OFFSET is the low-order word of a pointer (and 
the Linker doesn't care if the high-order word 
follows or not). 


3. A HIBYTE is the high-order half of an OFFSET (and 
the Linker doesn't care if the low-order half 
precedes or not). 


4. A LOBYTE is the low-order half of an OFFSET (and 
the Linker doesn't care if the high-order half 
follows or not). 
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Pointer: 
ee | 
(peso earner 
Base: 
(eee ecuador mead 
(eta EY 
Offset: 
(fac een eee 
jy 
Hibyte: 
freer oeeset 
femeoreeed 
Lobyte: 
een eecey 


Figure 6.1. LOCATION Types 


A LOCATION is specified by two data: (1) the LOCATION type, 
and (2) where the LOCATION is. The first is specified by 
the LOC subfield of the LOCAT field of the FIXUP record; 
the second is specified by the DATA RECORD OFFSET subfield 
of the LOCAT field of the FIXUP record. 


MODE - The Linker Supports two kinds of Eixups: 
"self-relative" and "“Ssegment-relative." 


Self-relative fixups Support the 8- and 16-bit offsets that 
are used in the CALL, JUMP and SHORT-JUMP instructions. 
Segment-relative fixups support all other addressing modes 
of the 8086. 


TARGET - The TARGET is the location in MAS being referenced. 
(More explicitly, the TARGET may be considered to be the 
lowest byte in the object being referenced.) A TARGET is 
specified in one of eight ways. There are four "primary" 
ways, and four "secondary" ways. Each primary way of 
specifying a TARGET uses two kinds of data: an 
INDEX-Or-FRAME-NUMBER 'X', and a displacement 'D'. 
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(TO) X 1S a SEGMENT INDEX. The TARGET is 
byte in the LSEG identified by the INDEX. 


(Tl) X 1S a GROUP INDEX. The TARGET is 
byte in the LSEG identified by the INDEX. 


the Dth 


the Dth 


(T2) X 1S an EXTERNAL INDEX. The TARGET is the Dth 
byte following the byte whose address is 
(eventually) given by the External Name identified 


by the INDEX. 


(T3) X 1S a FRAME NUMBER. The TARGET is 


the Dth 


byte in the FRAME identified by the FRAME NUMBER 


(i.e., the address of TARGET is (X*16)+D). 


Each secondary way of specifying a TARGET uses only 
item: the INDEX-or-FRAME-NUMBER pr An 
displacement equal to zero is assumed. 


(T4) X 1S a SEGMENT INDEX. The TARGET is 
(first) byte in the LSEG identified by the 


(T5) X 1S a GROUP INDEX. The TARGET is 


One data 
implicit 


the Oth 
INDEX. 


the Oth 


(first) byte in the LSEG in the specified group 


that is eventually LOCATEd lowest in MAS. 


(T6) X iS an EXTERNAL INDEX. The TARGET 


is the 


byte whose address is the External Name identified 


by the INDEX. 


(T7) X 1S a FRAME NUMBER. The TARGET is 
whose 20-bit address is (X*16). 


NOTE 


The Microsoft Linker does not 
Support methods T3 and T7. 


the byte 
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The following nomenclature is used to describe a TARGET: 


TARGET: SI(<segment name>), <displacement> [TO] 
TARGET: GI(<group name>), <displacement> [Tl] 
TARGET: EI(<symbol name>), <displacement> Cr | 
TARGET: SI (<Segment name>) [T4 } 
TARGET: GI (<group name>) TS] 
TARGET: EI (<Symbol name>) [T6] 


The following examples illustrate how this notation is used: 


TARGET: SI(CODE), 1024 The 1025th byte in 
the segment "CODE" 

TARGET: GI (DATAAREA) The location in MAS of 
a group called 
"DATAAREA" 

TARGET: EI(SIN) The address of the 
external subroutine 
"SIN* 

TARGET: EI (PAYSCHEDULE), 24 The 24th byte 


following the location 
of an EXTERNAL data 
Structure called 
"PAYSCHEDULE" 


FRAME - Every 8086 memory reference iS to ae location 
contained within some FRAME; where the FRAME is designated 
by the content of some segment register. For the Linker’ to 
form a correct, uSable memory reference, it must know what 
the TARGET is, and to which FRAME the reference is being 


made. Thus, every fixup specifies Such a FRAME, in one of 
six ways. Some ways use data, Xs which is in 
INDEX-Or-FRAME-NUMBER, aS~— above. Other wayS require no 


data. 
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The six ways of specifying frames are: 


(FO) X 1S a SEGMENT INDEX. The FRAME is~ the 
canonic FRAME of the LSEG defined by the INDEX. 


(Fl) X 1S a GROUP INDEX. The FRAME is the’ canonic 
FRAME defined by the group (i.e., the canonic FRAME 
defined by the LSEG in the group that is eventually 
LOCATEdG lowest in MAS). 


(F2) X 1S an EXTERNAL INDEX. The FRAME 1s 
determined when the External Name's public 
definition is found. There are 3 cases: 


(F2a) The symbol is defined relative to some 
LSEG, and there iS no associated GROUP. The 
LSEGS canonic FRAME is specified. 


(F2b) The symbol is defined absolutely, without 
reference to an LSEG, and there iS no 
associated GROUP. The FRAME iS_~ specified by 
the FRAME NUMBER sSubfield of the PUBDEF record 
that gives the symbol's definition. 


(F2c) Regardless of how the symbol is defined, 
there iS an associated GROUP. The canonic 
FRAME of the GROUP is specified. (The group is 
specified by the GROUP INDEX subfield of the 
PUBDEF Record.) 


(F3) X 1S a FRAME NUMBER (Specifying the obvious 
FRAME) . 


(F4) No X. The FRAME 1S the canonic FRAME of the 
LSEG containing LOCATION. 


(FS) No X. The FRAME is determined by the TARGET. 
There are four cases: 


(F5a) The TARGET specified a SEGMENT INDEX: in 
this case, the FRAME is determined as in (FO). 


(F5b) The TARGET specified a GROUP INDEX: in 
this case, the FRAME is determined as in (Fl). 


(FS5c) The TARGET specified an EXTERNAL INDEX: 
in this case, the FRAME is determined as in 
(FZ) x 


(F5d) The TARGET is specified with an explicit 
FRAME NUMBER: in this case the FRAME is 
determined as in (F3). 
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NOTE 


The Microsoft Linker does not 
Support frame methods F2b, F3, 
and F5d. 


Nomenclature describing FRAMES is Similar to the above 
nomenclature for TARGETs. 


FRAME: SI (<segment name>) [FO] 
FRAME: GI (<group name>) [Fl] 
FRAME: EI (<symbol name>) [F2] 
FRAME: LOCATION [F4] 
FRAME: TARGET [F5] 
FRAME: NONE [F6] 


For an 8086 memory reference, the FRAME specified by a 
self-relative reference is usually the canonic FRAME of the 
LSEG containing the LOCATION, and the FRAME specified by a 
segment relative reference is the canonic FRAME of the LSEG 
containing the TARGET. 


6.9 SELF-RELATIVE FIXUPS 


A self-relative fixup operates as follows: A memory address 
is implicitly defined by LOCATION; namely the address of 
the byte following LOCATION (because at the time of a 
self-relative reference, the 8086 IP (Instruction Pointer) 
is pointing to the byte following the reference). 


For 8086 self-relative references, if either LOCATION or 
TARGET are outside the specified FRAME, the Linker gives a 
warning. Otherwise, there iS a unique 16-bit displacement 
which, when added to the address’ implicitly defined by 
LOCATION, will yield the relative position of TARGET in the 
FRAME. 


If the LOCATION is an OFFSET, the displacement is added _ to 
LOCATION modulo 65536; no errors are reported. 
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If the LOCATION is a LOBYTE, the displacement must be within 
the range {-128:127}, otherwise the Linker will give a 
warning. The displacement is added to LOCATION modulo 256. 


If the LOCATION is a BASE, POINTER, Or HIBYTE, it iS unclear 
what the translator had in mind, and the action taken by the 
Linker is undefined. 


6.10 SEGMENT-RELATIVE FIXUPS 


A segment-relative fixup operates in the following way: a 
non-negative 16-bit number, FBVAL, is defined as the FRAME 
NUMBER of the FRAME specified by the fixup, and a_ signed 
20-bit number, FOVAL, is defined as the distance from the 
base of the FRAME to the TARGET. If this signed 20-bit 
number is less than 0O or greater than 65535, the Linker 
reports an error. Otherwise, FBVAL and FOVAL are used to 
fixup LOCATION in the following fashion: 


foie If LOCATION is a_ POINTER, then FBVAL is added 
(modulo 65536) to the high-order word of POINTER, 
and FOVAL is added (modulo 65536) to the low-order 
word of POINTER. 


2. If LOCATION is a BASE, then FBVAL is added (modulo 
65536) to the BASE; FOVAL is ignored. 


3. If LOCATION is an OFFSET, then FOVAL is-~ added 
(modulo 65536) to the OFFSET; FBVAL is ignored. 


4. If LOCATION is a HIBYTE, then (FOVAL/256) is added 
(modulo 256) to the HIBYTE; FBVAL iS ignored, 
(The indicated division is "integer division", 
i.e., the remainder is discarded.) 


5. If LOCATION is a LOBYTE, then (FOVAL modulo 256) is 
added (modulo 256) to the LOBYTE; FBVAL 1S 
ignored. 


6.11 RECORD ORDER 


A object code file must contain a Sequence of (one or’ more) 
modules, or a library containing zero or more modules. A 
module is defined as a collection of object code defined by 
a sequence of object records. The following syntax shows 
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the valid orderings of records to form a module. In 
addition, the given semantic rules provide information about 
how to interpret the record sequence. 


NOTE 


The syntactic description 
language used below is defined 
in WIRTH: CACM, November 
Lo vs VOL, 20; no. iL, 
pp. 822-823. The character 
strings represented by capital 
letters above are not literals 
but are identifiers that are 
further defined in the section 
describing the record formats. 


object file = tmodule 

tmodule = THEADR seg-grp {component}  modtail 

seg grp = {LNAMES} {SEGDEF} {TYPDEF | EXTDEF | GRPDEF} 
component = data | debug _ record 

data = content def thread def 


TYPDEF | PUBDEF | EXTDEF 


debug record = LINNUM 


content def = data record {FIXUPP} 
thread def = FIXUPP (containing only thread fields) 
data record = LIDATA | LEDATA 


modtail = MODEND 
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The following rules apply: 


1. A FIXUPP record always refers to the previous’ DATA 
record. 


2. All LNAMES, SEGDEF, GRPDEF, TYPDEF, and EXTDEF 


records muSt precede all records that refer to 
them. 


3. COMENT records may appear anywhere in a file, 


except as the first or last record ina file or 
module, or within a contentdef. 
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6.12 INTRODUCTION TO THE RECORD FORMATS 


The following pages present diagrams of record formats’. in 
schematic form. Here iS a sample record format, to 
illustrate the various conventions. 


SAMPLE RECORD FORMAT 
(SAMREC ) 


/ | || 


RECORD NAME NUMBER CHK 
TYP LENGTH SUM 









7 | | | 


rpt 
TITLE and OFFICIAL ABBREVIATION 


At the top is the name of the record format described, with 
an official abbreviation. To promote uniformity among 
various programs, including translators and debuggers, the 
abbreviation should be used in both code and documentation. 
The record format abbreviation is always six letters. 


The BOXES 


Each format is drawn with boxes of two sizes. The narrow 
boxes represent single bytes. The wide boxes represent two 
bytes each. The wide boxes with three slashes in the top 
and bottom represent a variable number of bytes, one or 
more, depending upon content. The wide boxes with four 
vertical bars in the top and bottom represent 4-byte fields. 


REC TYP 


The first byte in each record contains a value between 0 and 
255, indicating which record type the record is. 
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RECORD LENGTH 


The second field in each record contains the number of bytes 
in the record, exclusive of the first two fields. 


NAME 


Any field that indicates a "NAME" has the following internal 
structure: the first byte contains a number between 0 and 
127, inclusive, that indicates the number of remaining bytes 
in the field. The remaining bytes are interpreted as a byte 
string. 


Most translators constrain the character set to be a_ subset 
of the ASCII character set. 


NUMBER 


A 4-byte NUMBER field represents a 32-bit unsigned integer, 
where the first 8 bits (least-significant) are stored in the 
first byte (lowest address), the next 8 bits are stored in 
the second byte, and so on. 


REPEATED OR CONDITIONAL FIELDS 


Some portions of a record format contain a field or a series 
of fields that may be repeated one or more times. Such 
portions are indicated by the "repeated" or "rpt" brackets 
below the boxes. 


Similarly, some portions of a record format are present only 
if some given condition is true; these fields are indicated 
by Similar "conditional" or "cond" brackets below the boxes. 


CHK .SUM 


The last field in each record is a check sum, which contains 
the 2'S complement of the sum (modulo 256) of all other 
bytes in the record. Therefore, the sum (modulo 256) of all 
bytes in the record equals 0. 
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BIT FIELDS 


Descriptions of contents of fields will sometimes be at’ the 


bit level. Boxes with vertical lines drawn through them 
represent bytes or words; the vertical lines indicate bit 
boundaries; thus the byte represented below, has three 


bit-fields of 3-, l-, and 4-bits. 


T-MODULE HEADER RECORD 
(THEADR) 


/ / 


© CHK 
MODULE SUM 
NAME 











RECORD 
LENGTH 


/ 


Every module output from a translator must have a T-MODULE 
HEADER RECORD. 


T-MODULE NAME 


The T-MODULE NAME provides a name for the T~-MODULE. 
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LIST OF NAMES RECORD 


—_— —_ 





~ (LNAMES) 


1 | /- 


NAME 

















RECORD 
LENGTH 







i] 


rpt 


This Record provides a list of names that may be used in 
following SEGDEF and GRPDEF records as the names. of 
Segments, Classes and/or Groups. 


The ordering of LNAMES records within a module, together 
with the ordering of names within each LNAMES Record, 
induces an ordering on the names. Thus, these names are 
considered to be numbered: 1, 2, 3, 4, ... These numbers 
are used as "Name Indices" in the Segment Name Index, Class 
Name Index and Group Name Index fields of the SEGDEF and 
GRPDEF Records. 


NAME 


This repeatable field provides a name, which may have - zero 
length. 
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REC} RECORD 
TYP] LENGTH 
98H 


SEGMENT INDEX values 1 through 32767, which are used in 
other record types to refer to specific LSEGs, are defined 
implicitly by the sequence in which SEGDEF Records appear in 
the object file. 


SEGMENT DEFINITION RECORD 
(SEGDEF ) 


fT} 


SEGMENT 
ATTR 














1 / / 


SEG ATTR 


The SEG ATTR field provides information on various 
attributes of a Segment, and has the following format: 


ACB FRAME OFF 
y NUMBER SET 





conditional 


The ACBP byte contains four numbers which are the A, C, B, 
and P attribute specifications. This byte has the following 
format: 
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A (Alignment) is a 3-bit subfield that specifies the 
alignment attribute of the LSEG. The semantics are defined 
as follows: 


0 SEGDEF describes an absolute LSEG. 

1 SEGDEF describes a relocatable, byte-aligned LSEG. 

2 SEGDEF describes a relocatable, word-aligned LSEG. 

3 SEGDEF describes a relocatable, paragraph-aligned 
LSEG. 

=4 SEGGDEF describes a relocatable, page-aligned LSEG. 


If A=0, the FRAME NUMBER and OFFSET fields will be present. 
Using MS-LINK, absolute segments may be used for addressing 
purposes only; for example, defining the starting address 
of a ROM and defining symbolic names for addresses within 
the ROM. MS-LINK will ignore any data specified as 
belonging to an absolute LSEG. 


C (Combination) is a 3-bit subfield that specifies the 
combination attribute of the LSEG. Absolute segments (A=0) 
must have combination zero (C=0). For relocatable segments, 
the C field encodes a number (0,1,2,4,5,6 or 7) that 
indicates how the segment can be combined. The 
interpretation of this attribute is best given by 
considering how two LSEGS are combined: Let X,Y be  LSEGs, 
and let Z be the LSEG resulting from the combination of X,Y. 
Let LX and LY be the lengths of X and Y, and let MXY denote 
the maximum of LX, LY. Let G be the length of any gap 
required between the X- and Y-components of Z to accommodate 
the alignment attribute of Y. Let LZ denote the length of 
the (combined) LSEG Z; let dx (0<=dx<LX) be the offset in X 
of a byte, and let dy similarly be the offset in Y of a 
byte. The following table gives the length LZ of the 
combined LSEG 2Z, and the offsets dx' and dy' in Z for the 
bytes corresponding to dx in X and dy in Y. 


Table 6.2. Combination Attribute Example 


C LZ dx' dy' 

2 LX+LY+G dx dy+LxX+G "Public" 
5 LX+LY+G dx dy+LX+G "Stack" 
6 MXY dx dy "Common" 


Table 6.2 has no lines for C=0, C=l, C=3, C=4 and C=7. C=0 
indicates that the relocatable LSEG may not be combined; 
C=l1 and C=3 are undefined. C=4 and C=7 are treated like 
C=2. 
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B (Big) 1S a 1l-bit subfield which, if 1, indicates that the 


Segment Length iS exactly 64K (65536). In this case the 
SEGMENT LENGTH field must contain zero. 


The P field must always be zero. 


The FRAME NUMBER and OFFSET fields (present only for 
absolute segments, A=0) specify the placement in MAS of the 
absolute segment. The range of OFFSET is constrained to be 
between 0 and 15 inclusive. If a value larger than 15 is 
desired for OFFSET, then an adjustment of the FRAME NUMBER 
should be done. 


SEGMENT LENGTH 


The SEGMENT LENGTH field gives the length of the segment in 
bytes. The length may be zero; if so, MS-LINK will not 
delete the segment from the module. The SEGMENT LENGTH 
field is only big enough to hold numbers from 0 to 64K-1 
inclusive. The B attribute bit in the ACBP field (see SEG 
ATTR section) must be used to give the segment a length of 
64K. 


SEGMENT NAME INDEX 


The Segment Name iS a name the programmer or translator 
assigns to the segment. Examples: CODE, DATA, TAXDATA, 
MODULENAME CODE, STACK. This field provides the Segment 
Name, by indexing into the list of names provided by the 
LNAMES Record(s). 
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CLASS NAME INDEX 


The Class Name is a name the programmer or translator can 
assign to a segment. If none is aSSigned, the name is null, 
and has length 0. The purpose of Class Names is to allow 
the programmer to define a "handle" used in the ordering of 
the LSEGS in MAS. Examples: RED, WHITE, BLUE; ROM 
FASTRAM, DISPLAYRAM. This field provides the Class Name, by 


indexing into the list of names provided by the LNAMES 
Record(s). 


OVERLAY NAME INDEX 


NOTE 


This is ignored in MS-LINK 
versions 2.40 and later, but 
supported in all earlier 
versions. However, semantics 
differ from Intel semantics. 


The Overlay Name is a name the translator and/or MS-LINK, at 
the programmer's request, applies to a segment. The Overlay 
Name, like the Class Name, may be null. This field provides 
the Overlay Name, by indexing into the list of names 
provided by the LNAMES Record(s). 


NOTE 


The "Complete Name" of a 
segment is a 3-component 
entity comprising a Segment 
Name, a Class Name and an 
Overlay Name. (The latter two 
components may be null.) 
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GROUP DEFINITION RECORD 
(GRPDEF) 


1 | 





















RECORD GROUP GROUP 
LENGTH NAME COMPONENT 
INDEX DESCRIPTOR 


vt A 


repeated 


GROUP NAME INDEX 


The Group Name is a name by which a collection of LSEGS may 
be referenced. The important property of such a group is 
that, when the LSEGs are eventually fixed in MAS, there must 
exist some FRAME which "covers" every LSEG of the group. 


The GROUP NAME INDEX field provides the Group Name, by 
indexing into the list of mnames'- provided by the LNAMES 
Record(s). 


GROUP COMPONENT DESCRIPTOR 


Each GROUP COMPONENT DESCRIPTOR has the following format: 


vf 


SEGMENT 


INDEX 





The first byte of the DESCRIPTOR contains’ OFFH; the 
DESCRIPTOR contains one field, which is a SEGMENT INDEX that 
selects the LSEG described by a preceding SEGDEF record. 
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TYPE DEFINITION RECORD 
(TYPDEF) 


7 / t? 


























RECORD NAME EIGHT 
LENGTH (USUALLY LEAF 
NULL) DESCRIPTOR 


7 / / | 


repeated 


The Microsoft Linker uses TYPDEF records only for communal 
variable allocation. This is not Intel's intended purpose. 
See Section 6.15, "Microsoft Type Representations for 
Communal Variables." 


As many "EIGHT LEAF DESCRIPTOR" fields as necessary are used 
to describe a branch. (Every such field except the last in 
the record describes eight leaves; the last such field 
describes from one to eight leaves.) 


TYPE INDEX values 1 through 32767, which are contained in 
other record types to associate object types with object 
names, are defined implicitly by the sequence in which 
TYPDEF records appear in the object file. 


NAME 


Use of this field is reserved. Translators should place a 
Single byte containing 0 in it (which is the representation 
of a name of length zero). 
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EIGHT LEAF DESCRIPTOR 


This field can describe up to eight Leaves. 


iP 
E LEAF 
N DESCRIPTOR 
/ | | 
rpt 


The EN field is a byte: the 8 bits, left to right, indicate 


if the following 8 Leaves (left to right) are Easy (bit=0) 
or Nice (bdbit=1). 


The LEAF DESCRIPTOR field, which occurs between 1 and 8 
times, has one of the following formats: 


0 
to 
128 
0 
129 to 
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The first format (Single byte), containing a value between 0 
and 127, represents a Numeric Leaf whose value is the number 
given. 


The second format, with a leading byte containing 129, 


representS a Numeric Leaf. The number is contained in the 
following two bytes. 


The third format, with a leading byte containing 132, 
representS a Numeric Leaf. The number is contained in the 
following three bytes. 


The fourth format, with a leading byte containing 136, 
represents a Signed Numeric Leaf. The number is contained 
in the following four bytes, Sign extended if necessary. 
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PUBLIC NAMES DEFINITION RECORD 
(PUBDEF) 





i fA 


PUBLIC 
BASE 


J / 


PUBLIC 
NAME 


















REC RECORD 
LENGTH 


if GIF 


repeated 


This record provides a list of one or more PUBLIC NAMES; 
for each one, three data are provided: (1) a base value for 
the name, (2) the offset value of the name, and (3) the type 
of entity represented by the name. 


PUBLIC BASE 


The PUBLIC BASE has the following format: 


StF iP 


GROUP SEGMENT 
INDEX INDEX 














FRAME 
NUMBER 





tf fF its 


conditional 


The GROUP INDEX field has a format given earlier, and 
provides a number between 0 and 32767 inclusive. A non-zero 
GROUP INDEX associates a group with the public symbol, = and 
is used as described in Section 6.8, "Conceptual Framework 
for Fixups," case (F2c). A zero GROUP INDEX indicates” that 
there 1S no associated group. 


The SEGMENT INDEX field has a format given earlier, and 
provides a number between 0 and 32767, incluSive. 


A non-zero SEGMENT INDEX selects an LSEG. In this case, the 
location of each public symbol defined in the record is 
taken aS a non-negative displacement (given by a _ PUBLIC 
OFFSET field) from the first byte of the selected LSEG, and 
the FRAME NUMBER field must be absent. 
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A SEGMENT INDEX of 0 (legal only if GROUP INDEX is also _ QO) 
means that the location of each public symbol defined in the 
record is taken as a displacement from the base of the FRAME 
defined by the value in the FRAME NUMBER field. 


The FRAME NUMBER is present if both the SEGMENT INDEX = and 
GROUP INDEX are zero, 


A non-zero GROUP INDEX selects some group; this group is 
taken as the "frame of reference" for references to all 
public symbols defined in this’ record; that is, MS-LINK 
will perform the following actions: 


l. Any fixup of the form: 
TARGET: EI (P) 


FRAME: TARGET 


(where "P" is a public symbol in this PUBDEF 


record) will be converted by MS-LINK to a fixup of 
the form: 


TARGET: SI(L) ,d 
FRAME: GI(G) 


Where "SI(L)" and "d" are provided by the SEGMENT 
INDEX and PUBLIC OFFSET fields. (The “normal" 
action would have the frame specifier in the new 
fixup be the same as in the old fixup: FRAME: 
TARGET. ) 


2. When the value of a public symbol, as defined by 
the SEGMENT INDEX, PUBLIC OFFSET, and (optionally) 


FRAME NUMBER fields, is converted to a 
{base,offset} pair, the base part will be taken as 
the base of the indicated group. If a non-negative 


16-bit offset cannot then complete the definition 
of the public symbol's value, an error occurs. 


A GROUP INDEX of zero selects no group. MS-LINK will not 
alter the FRAME specification of fixups referencing the 
symbol, and will take, as the base part of the absolute 
value of the public symbol, the canonic frame of the segment 
(either LSEG or PSEG) determined by the SEGMENT INDEX field. 
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PUBLIC NAME 


The PUBLIC NAME field gives the name of the object whose 
location in MAS is made available to other modules. The 
name must contain one or more characters. 


PUBLIC OFFSET 


The PUBLIC OFFSET field is a 16-bit value, which is either 
the offset of the Public Symbol with respect to an LSEG (if 
SEGMENT INDEX > 0), or the offset of the Public Symbol with 
respect to the specified FRAME (if SEGMENT INDEX = 0). 


TYPE INDEX 


The TYPE INDEX field identifies a Single preceding TYPDEF 
(Type Definition) Record containing a descriptor for the 
type of entity represented by the Public Symbol. This field 
1S ignored by the Linker. 
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EXTERNAL NAMES DEFINITION RECORD 
(EXTDEF) 





// ae 


EXTERNAL TYPE 
NAME INDEX 







RECORD 
LENGTH 











/ ff oi + 


repeated 


This record provides a list of external names, and for’ each 
name, the type of object it represents. MS-LINK will assign 
to each External Name the value provided by an_ identical 
Public Name (if such a name is found). 


EXTERNAL NAME 


This field provides the name, which must have = non-zero 
length, of an external object. 


Inclusion of a Name in an External Names Record iS an 
implicit request that the object file be linked to a module 
containing the same name declared as a Public Symbol. This 
request obtains whether or not the External Name is 
referenced within some FIXUPP Record in the module. 


The ordering of EXTDEF Records within a module, together 
with the ordering of External Names within each EXTDEF 
Record, induces an ordering on the set of all External Names 
requested by the module. Thus, External Names” are 
considered to be numbered 1, 2, 3, 4, ge Se These numbers 
are used as "External Indices" in the TARGET DATUM and/or 
FRAME DATUM fields of FIXUPP Records to refer to a 
particular External Name. 
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NOTE 
8086 External Names are 
numbered positively: 
Lyf,aesca TRIS 168 @ @€hange 
from 8080 External Names, 
which were numbered Starting 
from zero: eke 24a es This 
conforms with other 8086 
Indices (Segment Index, Type 
Index, etc.) which use 0 asa 
default value with special 
meaning. 
External indices may not reference forward. For example, an 


external definition record defining the kth object must 
precede any record referring to that object with index k. 


TYPE INDEX 


This field identifies a single preceding TYPDEF (Type 
Definition) record containing a descriptor for the type of 
object named by the External Symbol. 


The TYPE INDEX is used only in communal variable allocation 
by the Microsoft Linker. 
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LINE NUMBERS RECORD 
(LINNUM) 





/ /- 
LINE 


NUMBER 
BASE 


/ /- 





















LINE 
NUMBER 
OFFSET 


RECORD 
LENGTH 


LINE 
NUMBER 







repeated 


This record provides the means by which a translator may 
pass the correspondence between a line number in source code 
and the corresponding translated code. 


LINE NUMBER BASE 


The LINE NUMBER BASE has the following format: 


ae a tT 
GROUP SEGMENT 
INDEX INDEX 
(ignored) 

ff P of F 


The SEGMENT INDEX determines the location of the first byte 
of code corresponding to some source line number. 


LINE NUMBER 


A line number between 0 and 32767, inclusive, is provided in 
binary by this field. The high-order bit is reserved for 
future use and must be zero. 


LINE NUMBER OFFSET 


The LINE NUMBER OFFSET field is a 16-bit value, which is the 
offset of the line number with respect to an LSEG (if 
SEGMENT INDEX > 0). 


INTEL RELOCATABLE OBJECT MODULE FORMATS Page 6-36 





ft P 






















RECORD SEGMENT ENUMERATED 
LENGTH INDEX DATA 
OFFSET 


iff 


=rot- 


This record provides contiguous data from which a portion of 
an 8086 memory image may be constructed. 


SEGMENT INDEX 


This field must be non-zero and specifies an index relative 
to the SEGMENT DEFINITION RECORDS’ found previous to the 
LEDATA RECORD. 


ENUMERATED DATA OFFSET 


This field specifies an offset that is relative to the base 
of the LSEG that is specified by the SEGMENT INDEX and 
defines the relative location of the first byte of the DAT 
field. Successive data bytes in the DAT field occupy 
succesSively higher locations of memory. 


DAT 


This field provides up to 1024 consecutive bytes of 
relocatable or absolute data. 
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LOGICAL ITERATED DATA RECORD 





(LIDATA) 


of P iP 




















RECORD SEGMENT ITERATED ITERATED CHK 
LENGTH INDEX DATA DATA SUM 
OFFSET BLOCK 


1 | /- 1 | / 


—-repeated-- 


This record provides contiguous data from which a portion of 
an 8086 memory image may be constructed. 


SEGMENT INDEX 


This field must be non-zero and specifies an index relative 
to the SEGDEF records found previous to the LIDATA RECORD. 


ITERATED DATA OFFSET 


This field specifies an offset that is relative to the base 
of the LSEG that iS specified by the SEGMENT INDEX and 
defines the relative location of the first byte in the 
ITERATED DATA BLOCK. Successive data bytes in the ITERATED 
DATA BLOCK occupy successively higher locations of memory. 
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ITERATED DATA BLOCK 


This repeated field is a structure specifying tthe repeated 
data bytes. The structure has the following format: 


J | /' 












REPEAT 


COUNT CONTENT 


7 / / 


NOTE 


The Linker cannot handle 
LIDATA records whose ITERATED 
DATA BLOCK is larger than 512 
bytes. 


REPEAT COUNT 


This field specifies the number of times that the CONTENT 


portion of this ITERATED DATA BLOCK is to be repeated. 
REPEAT COUNT must be non-zero. 


BLOCK COUNT 


This field specifies the number of ITERATED DATA BLOCKS that 
are to be found in the CONTENT portion of this ITERATED DATA 
BLOCK . If this field has value zero, then the CONTENT 
portion of this ITERATED DATA BLOCK is interpreted as data 
bytes. If non-zero, then the CONTENT portion is interpreted 
as that number of ITERATED DATA BLOCKs. 
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CONTENT 


This field may be interpreted in one of two ways, depending 
on the value of the previous BLOCK COUNT field. 


If BLOCK COUNT is zero then this field is a 1l-byte count 
followed by the indicated number of data bytes. 


If BLOCK COUNT iS non-zero then this field is interpreted as 
the first byte of another ITERATED DATA BLOCK. 


NOTE 


From the outermost level, the 
number of nested ITERATED DATA 
BLOCKS is limited to 17, 1.e., 
the number of levels of 
recursion is limited to 17. 
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FIXUP RECORD 
(FIXUPP) 


J / /- 











RECORD THREAD CHK 
LENGTH Or SUM 
FIXUP 


7 | | 


rpt 


This record specifies 0 or more fixups. Each fixup requests 
a modification (fixup) to a LOCATION within the previous 
DATA record. A data record may be followed by more than one 


fixup record that refers. Each fixup is specified by a 
FIXUP field that specifies 4 data: a location, a mode, a 
target and ae frame. The frame and the target may be 


specified totally within the FIXUP field, or may be 
specified by reference to a preceding THREAD field. 


A THREAD field specifies a default target or frame that may 
subsequently be referred to in identifying a target or a 
frame. Eight threads are _ provided; four for frame 
Specification and four for target specification. Once a 
target or frame has been specified by a THREAD, it may _ be 
referred to by following FIXUP fields (in the same or 
following FIXUPP records), until another THREAD field with 
the same type (TARGET Or FRAME) and Thread Number (0 - 3) 
appears (in the same or another FIXUPP record). 


THREAD 
THREAD is a field with the following format: 


i i 


TRD INDEX 


J / / 


conditional 
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The TRD DAT (ThReaD DATa) subfield is a byte with this 
internal structure: 





The 'Z' is a 1l-bit subfield, currently without any defined 
function, that is required to contain 0. 


The 'D' subfield is one bit that identifies what type of 
thread is being specified. If D=0, then a target thread is 
being defined; if D=l, then a frame thread is_ being 
defined. 


METHOD is a 3 bit subfield containing a number between 0 and 
3 (D=0) Or a number between 0 and 6 (D=1). 


Tt D=0, then METHOD = (0, 1, 2, 3, 4, 5S, 6, 7) mod 4, where 
the 0, ..., 7 indicate methods TO, ..., T7 of specifying a 
target. Thus, METHOD indicates what kind of Index or Frame 
Number is required to specify the target, without indicating 
if the target will be specified in a primary or secondary 
way. Note that methods 2b, 3, and 7 are not Supported by 
MS-LINK. 


If D=l, then METHOD = 0O, 1, 2, 4, #5, corresponding to 
methods FO, ..., of specifying a frame. Here, METHOD 
indicates what kind (if any) of Index is required to specify 
the frame. Note that methods 3 and 5d are not Supported by 
MS-LINKE. 


THRED is a number between 0 and 3, and associates a Thread 
Number to the frame or target defined by the THREAD field. 


INDEX contains a Segment Index, Group Index, or External 
Index depending on the specification in the METHOD subfield. 
This subfield will not be present if F4 or F5 are specified 
by METHOD. 
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FIXUP 


FIXUP is a field with the following format: 


/ | p> / /- 
TARGET TARGET 
DATUM DIS- 
PLACEMENT 
S| / if 
conditionaltconditionaltconditional 


LOCAT is a byte pair with the following format: 

















lo byte hi byte 


M iS a one-bit subfield that specifies the mode of the 
fixups: self-relative (M=0) or segment-relative (M=1). 


NOTE 


Self-relative fixups may NOT 
be applied to LIDATA records. 


S is a one-bit subfield that specifies that the length of 
the TARGET DISPLACEMENT subfield, if present (see below), in 
this FIXUP field will be either two bytes (containing a 
16-bit non-negative number, S=0) or three bytes (containing 
a signed 24-bit number in 2's complement form, S=1). 


NOTE 


3-byte subfields are a 
possible future extension, and 
are not currently supported. 
Thus, S=0 is currently 
mandatory. 
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LOC is a 3-bit subfield indicating that the byte(s) in the 
preceding DATA Record to be fixed up are a 'lobyte' (LOC=0), 
an 'offset' (LOC=1), a "base" (LOC=2), a "pointer" (LOC=3) , 
or a “hibyte"™ (LOC=4). (Other values in LOC are invalid.) 


The DATA RECORD OFFSET iS a number between O and 41023, 
inclusive, that gives the relative position of the lowest 
order byte of LOCATION (the actual bytes being fixed up) 
within the preceding DATA record. The DATA RECORD OFFSET is 
relative to the first byte in the data fields in the DATA 
RECORDs. 


NOTE 


If the preceding DATA record 
is an LIDATA record, it is 
possible for the value of DATA 
RECORD OFFSET to designate a 
"location" within a REPEAT 
COUNT subfield or a BLOCK 
COUNT subfield of the ITERATED 
DATA field. Such a reference 
is an error. MS-LINK's action 
on such a malformed record is 
undefined. 


FIX DAT is a byte with the following format: 





See Note l See Note 2 


Note l: Frame method 2b, F3, and F5d are not Supported. 


Note 2: Target method T3 and T7 are not Supported. 
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F is a l-bit subfield that svecifies whether the frame for 


this FIXUP is specified by a thread (F=l) or explicitly 
(F=0). 


FRAME 1S a number interpreted in one of two wayS-~ as 
indicated by tthe F bit. If F is zero, FRAME is a number 
between 0 and 5 and corresponds to methods FO, oe ey ES -6f 
specifying a FRAME. If F=1l, then FRAME is a thread number 
(0-3). It specifies the frame most recently defined by a 
THREAD field that defined a frame thread with the same 
thread number. (Note that the THREAD field may appear in 
the same, Or in an earlier FIXUPP record.) 


T 1S a l-bit Subfield that specifies whether the target 
Specified for this fixup is defined by reference to a thread 
(T=1), Or iS given explicitly in the FIXUP field (T=0). 


P is a l-bit subfield that indicates whether the target is 
Specified in a primary way (requires a TARGET DISPLACEMENT, 
P=0) or specified in a Secondary way (requires no TARGET 
DISPLACEMENT, P=1). Since a target thread does not have a 
primary/secondary attribute, the P bit is the only field 
that specifies the primary/secondary attribute of the target 
specification. 


TARGT iS interpreted as a 2-bit subfield. When T=0, it 
provides a number between 0 and 3, corresponding to methods 
TO, sss) TS OF T4, «cxy TH, depending on the value of PP (P 
can be interpreted as the high-order bit of TO, ..., T7). 
When the target is specified by a thread (T=1), then TARGT 
specifies a thread number (0-3). 


FRAME DATUM is the "referent" portion of a frame 
specification, and is a Segment Index, a Group Index, an 
External Index. The FRAME DATUM subfield 1s present only 
when the frame is specified neither by a thread (F=0) nor 
explicitly by methods F4 or F5 or F6. 


INTEL RELOCATABLE OBJECT MODULE FORMATS Page 6-45 


TARGET DATUM is the "referent" portion of a target 
Specification, and is a Segment Index, a Group Index, an 
External Index or a Frame Number. The TARGET DATUM subfield 


is present only when the target iS not specified by a thread 
(T=0). 


TARGET DISPLACEMENT is the 2-byte displacement required by 


"Drimary" ways of specifying TARGETS. This 2-byte subfield 
1S present if P=0. 


NOTE 
All these methods are 
described in Section 6.8, 
"Conceptual Framework for 


Fixups." 
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MODULE END RECORD 
(MODEND) 









RECORD START 
LENGTH ADDRS 





conditional 


This record serves two purposes. It denotes the end of a 
module and indicates whether the module just terminated has 
a specified entry point for initiation of execution. If the 
latter is true, the execution address is specified. 


MOD TYP 


This field specifies the attributes of the module. The bit 
allocation and associated meanings are as follows: 





MATTR iS a 2-bit subfield that specifies the following 
module attributes: 


MATTR MODULE ATTRIBUTE 

0 Non-main module with no START ADDRS 
l Non-main module with START ADDRS 

2 Main module with no START ADDRS 

3 Main module with START ADDRS 


L indicates whether the START ADDRS field is interpreted as 
a logical address that requires fixing up by MS-LINK. 
(L=1). Note: with MS-LINK, L muSt always equal l. 


Z indicates that this bit has not currently been assigned a 
function. These bits are required to be zero. 
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The START ADDRS field (present only if MATTR is 1 or 3) _ has 
the following format: 


START ADDRS 


| 

















END FRAME TARGET TARGET 
DAT DATUM DATUM DIS= 
PLACEMENT 


Tf i /- 


conditional+tconditional*tconditional 


The starting address of a module has all the attributes of 
any other logical reference found in a module. The mapping 
of a logical starting address to a physical starting address 
is done in exactly the Same manner aS mapping any other 
logical address to a physical address as specified in the 
discussion of fixups and the FIXUPP record. The above 
subfields of the START ADDRS field have the same semantics 
as the FIX DAT, FRAME DATUM, TARGET DATUM, and TARGET 
DISPLACEMENT fields in the FIXUPP- record. Only "“primary" 
fixups are allowed. Frame method F4 is not allowed. 
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COMMENT RECORD 
(COMENT ) 


/ | 
COMMENT CHK 
TYPE COMMENT SUM 
1 / / 


This record allows translators to include commentary 
information in object text. 












RECORD 
LENGTH 


COMMENT TYPE 


This field indicates the type of comment carried by this 


record. This allows commentary information to be structured 
for those processes that wish to selectively act on 
comments. The format of this field is as follows: 





N N COMMENT 
P L Z Z Z Z Z Z CLASS 


The NP (NOPURGE) bit, if 1, indicates that it 1S not able to 
be purged by object file utility programs which implement 
the capability of deleting COMENT record. 


The NL (NOLIST) bit, if 1, indicates that the text in the 
COMMENT field is not to be listed in the listing file of 
object file utility programs which implement the capability 
of listing object COMENT records. 
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The COMMENT CLASS field is defined as follows: 


0 Language translator comment. 

1 Intel copyright comment. The NP bit must be 
set. 

2~155 Reserved for Intel use. (See note 1.) 


156-255 Reserved for users. Intel products will 


COMMENT 


apply no semantics to these values. (See 
note 2.) 


This field provides the commentary information. 


Notes: 


Le 


Class value 129 is used to specify a library to add 
to the lLinker's library search list. The comment 


field will contain the name of the library. Note 
that unlike all other name _ specifications, the 
library name is not prefixed with its length. Its 


length is determined by the record length. The 
"NODEFAULTLIBRARYSEARCH" switch causes the linker 
to ignore all comment records whose class value is 
129% 


Class value 156 is used to specify a DOS level 
number. When the class value is 156, the comment 
field will contain a two-byte integer specifying a 
DOS level number. 
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6.13 NUMERIC LIST OF RECORD TYPES 


*6E RHEADR 
*70 REGINT 
*72 REDATA 
*74 RIDATA 
*76 OVLDEF 
*78 ENDREC 
*7A BLKDEF 
*7C BLKEND 
*7E DEBSYM 
80 THEADR 
*82 LHEADR 
*84 PEDATA 
*86 PIDATA 
88 COMENT 
8A MODEND 
8C EXTDEF 
8E TYPDEF 
90 PUBDEF 
*92 LOCSYM 
94 LINNUM 
96 LNAMES 
98 SEGDEF 
9A GRPDEF 
9C FIXUPP 
*9E (none) 
AO LEDATA 
A2 LIDATA 
*A4 LIBHED 
*A6 LIBNAM 
*A8 LIBLOC 
*AA LIBDIC 


NOTE 


Record types preceded by = an 
asterisk (*) are not supported 
by the Microsoft Linker. They 
will be ignored if they are 
found in an object module. 


INTEL RELOCATABLE OBJECT MODULE FORMATS Page 6-51 


6.14 INTEL TYPE REPRESENTATIONS 


NOTE 
The following section 
describes the Intel standard 
for type records. Section 
Gu LS, "Microsoft Type 
Representations," describes 


the Microsoft standard. 


The leaves in the following diagrams may be Numeric’ Leaves 
without relations, String Leaves, Index Leaves or Null 


Leaves. Andleaves and Orleaves are not supported at this 
time. 
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Types may be defined by branches of the following forms: 





(length) (Scalar type) 


POINTER 









STRUCTURE] (length) | (number of components)}|@list of component: 
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>ROCEDURE {number of parameters) 


where "(scalar type)" can be either UNSIGNED INTEGER, SIGNED 
INTEGER, Or REAL, "(return)" can be either SHORT or LONG 
(which indicates, in the case of a LABEL, whether a jump to 
the label should be a "short" jump or a "long" jump, 
respectively), and the following values are assigned: 


99 INTERRUPT 114 LONG 

100 FILE 115 SHORT 

101 PACKED 116 PROCEDURE 

102 UNPACKED 117 PARAMETER 

103 SET 118 DIMENSION 

104 (Reserved for length) 119 ARRAY 

105 CHAMELEON 120 (Reserved for length) 
106 BOOLEAN 121 STRUCTURE 

107 TRUE 122 POINTER 

108 FALSE 123 SCALAR 

109 CHAR 124 UNSIGNED INTEGER 
110 INTEGER 125 SIGNED INTEGER 
111 CONST 126 REAL 

112 (Reserved for length) 127 LIST 


113 LABEL 
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NOTE 


The previous (decimal) values 
are chosen for the convenience 
of wWtility programs. All 
numbers are different 
(although conceptually there 
1S no reason why REAL and 
SCALAR, for example, can't be 
the Same number), and are 
rather large, so that object 
module display programs may 
correctly decide whether to 
represent a Numeric Leaf as a 
number or aS an identifier, 
make this choice correctly 
most of the time, and never 
give a wrong identifier. 


INTEL RELOCATABLE OBJECT MODULE FORMATS Page 6-55 


6.15 MICROSOFT TYPE REPRESENTATIONS FOR COMMUNAL VARIABLES 


This section defines the Microsoft standard for communal 
variable allocation on the 8086 and 80286. 


A communal variable iS an uninitialized public’ variable 
whose final size and location are not fixed at compile time. 
Communal variables are similar to FORTRAN common blocks. in 
that if a communal variable is declared in more than one 
object module being linked together, then its actual size 
will be the largest size specified in the several 
declarations. In the C language, all uninitialized public 
variables are communal. The following example shows three 
different declarations of the same C communal variable: 


char foo[4]; fe In Tile a,c */ 
char foo[l]; /* In file b.c */ 
char foo[1024]; /* in file ¢,.c */ 


If the objects produced from a.c, b.c, and c.c are linked 
together, then the linker will allocate 1024 bytes for the 
char array foo. 


A communal variable is defined in the object text py an 
external definition record (EXTDEF) and the type definition 
record (TYPDEF) to which it refers. 


The TYPDEF for a communal variable has the following format: 







f/f 
EIGHT 
LEAF 

DESCRIPTOR 


4 FF 








REC RECORD 
Tre LENGTH 
8EH 


The EIGHT LEAF DESCRIPTOR field has the following format: 


fi 
6 LEAF 
DESCRIPTOR 
, tf 
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The EN field specifies whether the next 8 leaves in the LEAF 
DESCRIPTOR field are EASY (bit = 0) or NICE (bit = 1). This 
byte 1S always zero for TYPDEFS for communal variables. 


The LEAF DESCRIPTOR field has one of the following two 
formats. The format for communal variables in the default 
data segment (near variables) is as follows: 


1 ff 
LENGTH 










J / 
VAR 
SUBTYP 







(Optional) 


The VARiable TYPe field may be either SCALAR (7BH), STRUCT 
(79H), Or ARRAY (77H). The VAR SUBTYP field (if any) is 
ignored by the Linker. The format for communal variables 
not in the default data segment (far variables) is as 








follows: 
Sf / i fF 
NUMBER ELEMENT 
OF TYPE 
ELEMENTS INDEX 
a} f 1 | /- 
The VARiable TYPe field must be ARRAY (77H). The length 


field specifies the NUMBER OF ELEMENTS, and the ELEMENT TYPE 
INDEX is an index to a_previously defined TYPDEF whose 
format is that of a near communal variable. 


The format for the LENGTH IN BITS or NUMBER OF ELEMENTS 
fields is the same as the format for the LEAF DESCRIPTOR 
field, described in the TYPDEF record format section of this 
manual. 
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Link time semantics: 


All EXTDEFs referencing a TYPDEF of one of the _ previously 
described formats are treated as communal variables. All 
Others are treated as externally defined symbols for which a 
matching public symbol definition (PUBDEF) iS expected. A 
PUBDEF matching a communal variable definition will override 
the communal variable definition. Two Or more matching 
communal variable definitions must agree on whether’ the 
variable in question is near or far; the Linker issues a 
warning if there is a conflict. 


If the variable is near, then its size is the largest of the 
sizes specified for it. If the variable is far, then the 
Linker issues a warning if there are conflicting array 
element size specifications; if there are no- such 
conflicts, then the variable's size is the element’ size 
times the largest number of elements specified. The sum of 
the sizes of all near variables must not exceed 64K bytes. 
The sum of the sizes of all far variables must not exceed 
the size of the machine's addressable memory space. 


“Huge” communal variables: 


A tar communal variable whose size is larger than 64K _ bytes 
will reside in segments that are contiguous (8086) or have 
consecutive selectors (80286). No other data items will 
reside in the segments occupied by a huge communal variable. 
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